feat(svelte): format component (#3188)

* feat(svelte): add format component

* docs: update changelog

* fix: types

* fix: types

packages/svelte/CHANGELOG.md

@@ -6,6 +6,8 @@ description: All notable changes will be documented in this file.
 
 ## [Unreleased]
 
+- Added `Format` component.
+
 ## [0.2.0] - 2024-12-12
 
 ## Added

packages/svelte/src/lib/components/format/examples/byte-basic.svelte

@@ -0,0 +1,10 @@
+<script lang="ts">
+  import { Format } from '@ark-ui/svelte/format'
+
+  const value = 1450.45
+</script>
+
+<div>
+  File size:
+  <Format.Byte {value} />
+</div>

packages/svelte/src/lib/components/format/examples/byte-sizes.svelte

@@ -0,0 +1,13 @@
+<script lang="ts">
+  import { Format } from '@ark-ui/svelte/format'
+
+  const byteSizes = [50, 5000, 5000000, 5000000000]
+</script>
+
+<div>
+  {#each byteSizes as size, index (index)}
+    <div>
+      <Format.Byte value={size} />
+    </div>
+  {/each}
+</div>

packages/svelte/src/lib/components/format/examples/byte-with-locale.svelte

@@ -0,0 +1,17 @@
+<script lang="ts">
+  import { Format } from '@ark-ui/svelte/format'
+  import { LocaleProvider } from '@ark-ui/svelte/locale'
+
+  const locales = ['de-DE', 'zh-CN']
+  const value = 1450.45
+</script>
+
+<div>
+  {#each locales as locale (locale)}
+    <div>
+      <LocaleProvider {locale}>
+        <Format.Byte {value} />
+      </LocaleProvider>
+    </div>
+  {/each}
+</div>

packages/svelte/src/lib/components/format/examples/byte-with-unit-display.svelte

@@ -0,0 +1,14 @@
+<script lang="ts">
+  import { Format } from '@ark-ui/svelte/format'
+
+  const value = 50345.53
+  const unitDisplays = ['narrow', 'short', 'long'] as const
+</script>
+
+<div>
+  {#each unitDisplays as unitDisplay (unitDisplay)}
+    <div>
+      <Format.Byte {value} {unitDisplay} />
+    </div>
+  {/each}
+</div>

packages/svelte/src/lib/components/format/examples/byte-with-unit.svelte

@@ -0,0 +1,11 @@
+<script lang="ts">
+  import { Format } from '@ark-ui/svelte/format'
+
+  const value = 1450.45
+  const unit = 'bit'
+</script>
+
+<div>
+  File size:
+  <Format.Byte {value} {unit} />
+</div>

packages/svelte/src/lib/components/format/examples/number-basic.svelte

@@ -0,0 +1,5 @@
+<script lang="ts">
+  import { Format } from '@ark-ui/svelte/format'
+</script>
+
+<Format.Number value={1450.45} />

packages/svelte/src/lib/components/format/examples/number-with-compact.svelte

@@ -0,0 +1,5 @@
+<script lang="ts">
+  import { Format } from '@ark-ui/svelte/format'
+</script>
+
+<Format.Number value={1500000} notation="compact" compactDisplay="short" />

packages/svelte/src/lib/components/format/examples/number-with-currency.svelte

@@ -0,0 +1,5 @@
+<script lang="ts">
+  import { Format } from '@ark-ui/svelte/format'
+</script>
+
+<Format.Number value={1234.45} style="currency" currency="USD" />

packages/svelte/src/lib/components/format/examples/number-with-locale.svelte

@@ -0,0 +1,8 @@
+<script lang="ts">
+  import { Format } from '@ark-ui/svelte/format'
+  import { LocaleProvider } from '@ark-ui/svelte/locale'
+</script>
+
+<LocaleProvider locale="de-DE">
+  <Format.Number value={1450.45} />
+</LocaleProvider>

packages/svelte/src/lib/components/format/examples/number-with-percentage.svelte

@@ -0,0 +1,5 @@
+<script lang="ts">
+  import { Format } from '@ark-ui/svelte/format'
+</script>
+
+<Format.Number value={0.145} style="percent" maximumFractionDigits={2} minimumFractionDigits={2} />

packages/svelte/src/lib/components/format/examples/number-with-unit.svelte

@@ -0,0 +1,5 @@
+<script lang="ts">
+  import { Format } from '@ark-ui/svelte/format'
+</script>
+
+<Format.Number value={384.4} style="unit" unit="kilometer" />

packages/svelte/src/lib/components/format/format-byte.svelte

@@ -0,0 +1,30 @@
+<script module lang="ts">
+  export interface FormatByteProps {
+    /**
+     * The unit granularity to display
+     */
+    unit?: 'bit' | 'byte'
+    /**
+     * The unit display
+     */
+    unitDisplay?: 'long' | 'short' | 'narrow'
+    /**
+     * The byte size to format
+     */
+    value: number
+  }
+</script>
+
+<script lang="ts">
+  import { formatBytes } from '@zag-js/i18n-utils'
+  import { useLocaleContext } from '../../providers'
+
+  const props: FormatByteProps = $props()
+  const locale = useLocaleContext()
+  const text = $derived(() => {
+    const { value, ...intlProps } = props
+    return formatBytes(value, locale.locale, intlProps)
+  })
+</script>
+
+{text()}

packages/svelte/src/lib/components/format/format-number.svelte

@@ -0,0 +1,34 @@
+<script module lang="ts">
+  export interface FormatNumberProps {
+    /**
+     * The number to format
+     */
+    value: number
+    compactDisplay?: 'short' | 'long' | undefined
+    notation?: 'standard' | 'scientific' | 'engineering' | 'compact' | undefined
+    signDisplay?: 'auto' | 'never' | 'always' | 'exceptZero' | undefined
+    style?: string | undefined
+    unit?: string | undefined
+    unitDisplay?: 'short' | 'long' | 'narrow' | undefined
+    currency?: string | undefined
+    currencyDisplay?: string | undefined
+    currencySign?: string | undefined
+    maximumFractionDigits?: number | undefined
+    minimumFractionDigits?: number | undefined
+  }
+</script>
+
+<script lang="ts">
+  import { formatNumber } from '@zag-js/i18n-utils'
+  import { useLocaleContext } from '../../providers'
+
+  const props: FormatNumberProps = $props()
+  const locale = useLocaleContext()
+  const text = $derived(() => {
+    const { value, ...intlProps } = props
+    // @ts-expect-error TS 5.5.2
+    return formatNumber(value, locale.locale, intlProps)
+  })
+</script>
+
+{text()}

packages/svelte/src/lib/components/format/format.stories.ts

@@ -0,0 +1,84 @@
+import type { Meta } from '@storybook/svelte'
+import ByteBasicExample from './examples/byte-basic.svelte'
+import ByteSizesExample from './examples/byte-sizes.svelte'
+import ByteWithLocaleExample from './examples/byte-with-locale.svelte'
+import ByteWithUnitDisplayExample from './examples/byte-with-unit-display.svelte'
+import ByteWithUnitExample from './examples/byte-with-unit.svelte'
+import NumberBasicExample from './examples/number-basic.svelte'
+import NumberWithCompactExample from './examples/number-with-compact.svelte'
+import NumberWithCurrencyExample from './examples/number-with-currency.svelte'
+import NumberWithLocaleExample from './examples/number-with-locale.svelte'
+import NumberWithPercentageExample from './examples/number-with-percentage.svelte'
+import NumberWithUnitExample from './examples/number-with-unit.svelte'
+
+const meta = {
+  title: 'Components / Format',
+} as Meta
+
+export default meta
+
+export const NumberBasic = {
+  render: () => ({
+    Component: NumberBasicExample,
+  }),
+}
+
+export const NumberWithCompact = {
+  render: () => ({
+    Component: NumberWithCompactExample,
+  }),
+}
+
+export const NumberWithCurrency = {
+  render: () => ({
+    Component: NumberWithCurrencyExample,
+  }),
+}
+
+export const NumberWithLocale = {
+  render: () => ({
+    Component: NumberWithLocaleExample,
+  }),
+}
+
+export const NumberWithPercentage = {
+  render: () => ({
+    Component: NumberWithPercentageExample,
+  }),
+}
+
+export const NumberWithUnit = {
+  render: () => ({
+    Component: NumberWithUnitExample,
+  }),
+}
+
+export const ByteBasic = {
+  render: () => ({
+    Component: ByteBasicExample,
+  }),
+}
+
+export const ByteSizes = {
+  render: () => ({
+    Component: ByteSizesExample,
+  }),
+}
+
+export const ByteWithLocale = {
+  render: () => ({
+    Component: ByteWithLocaleExample,
+  }),
+}
+
+export const ByteWithUnit = {
+  render: () => ({
+    Component: ByteWithUnitExample,
+  }),
+}
+
+export const ByteWithUnitDisplay = {
+  render: () => ({
+    Component: ByteWithUnitDisplayExample,
+  }),
+}

packages/svelte/src/lib/components/format/format.ts

@@ -0,0 +1,10 @@
+export {
+  default as Byte,
+  type FormatByteProps as ByteProps,
+  type FormatByteProps as ByteBaseProps,
+} from './format-byte.svelte'
+export {
+  default as Number,
+  type FormatNumberProps as NumberProps,
+  type FormatNumberProps as NumberBaseProps,
+} from './format-number.svelte'

packages/svelte/src/lib/components/format/index.ts

@@ -0,0 +1,10 @@
+export {
+  default as FormatByte,
+  type FormatByteProps,
+} from './format-byte.svelte'
+export {
+  default as FormatNumber,
+  type FormatNumberProps,
+} from './format-number.svelte'
+
+export * as Format from './format'

packages/svelte/src/lib/components/index.ts

@@ -1,5 +1,6 @@
 export * from './avatar'
 export * from './factory'
+export * from './format'
 export * from './frame'
 export * from './highlight'
 export * from './portal'