Skip to content

An open source design system that's fully customizable and agent ready

TypeScript

docs(useLocale): add an invoice summary example block (#9511)

Parman Mohammadalizadeh96066d710a45
diff --git a/.changeset/use-locale-invoice-summary-example.md b/.changeset/use-locale-invoice-summary-example.md
new file mode 100644
index 0000000000..3310629841
--- /dev/null
+++ b/.changeset/use-locale-invoice-summary-example.md
@@ -0,0 +1,7 @@
+---
+'@astryxdesign/cli': patch
+---
+
+[docs] A new `useLocale — Invoice Summary` example block formats an invoice date and amount with `Intl` using the locale from `useLocale`, so switching the provider from English to German changes "Nov 2, 2026 · $1,234.50" to "2. Nov. 2026 · 1.234,50 $" with no second locale source. Copy it with `astryx template useLocaleHookUsage <path>`.
+
+@MannXo
diff --git a/apps/sandbox/scripts/next-export-routes.json b/apps/sandbox/scripts/next-export-routes.json
index 3055c02933..1042802df8 100644
--- a/apps/sandbox/scripts/next-export-routes.json
+++ b/apps/sandbox/scripts/next-export-routes.json
@@ -790,6 +790,7 @@
"/templates/useGridFocusHookUsage/",
"/templates/useKeyboardHintHookUsage/",
"/templates/useListFocusHookUsage/",
+ "/templates/useLocaleHookUsage/",
"/templates/useOutlineFromMarkdownHookUsage/",
"/templates/useOverflowHookUsage/",
"/templates/usePressFeedbackHookUsage/",
diff --git a/internal/shadcn-registry/routes.lock.json b/internal/shadcn-registry/routes.lock.json
index f37c3d346c..8bc50afd3e 100644
--- a/internal/shadcn-registry/routes.lock.json
+++ b/internal/shadcn-registry/routes.lock.json
@@ -3701,6 +3701,11 @@
"path": "examples/use-list-focus/recent-files",
"aliases": []
},
+ {
+ "name": "example-use-locale-invoice-summary",
+ "path": "examples/use-locale/invoice-summary",
+ "aliases": []
+ },
{
"name": "example-use-outline-from-markdown-docs-article",
"path": "examples/use-outline-from-markdown/docs-article",
diff --git a/packages/cli/api/template/use-locale-hook-usage.test.tsx b/packages/cli/api/template/use-locale-hook-usage.test.tsx
new file mode 100644
index 0000000000..7026b6a2da
--- /dev/null
+++ b/packages/cli/api/template/use-locale-hook-usage.test.tsx
@@ -0,0 +1,53 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+// @vitest-environment jsdom
+
+/**
+ * The useLocale example formats its invoice date and amount with the
+ * provider locale the hook returns, so switching the provider to German
+ * reformats both.
+ */
+
+import {act} from 'react';
+import {createRoot, type Root} from 'react-dom/client';
+import {afterEach, describe, expect, it} from 'vitest';
+import UseLocaleHookUsage from '../../assets/templates/blocks/components/Hooks/useLocaleHookUsage';
+
+(globalThis as {IS_REACT_ACT_ENVIRONMENT?: boolean}).IS_REACT_ACT_ENVIRONMENT =
+ true;
+
+let root: Root | null = null;
+let container: HTMLElement;
+
+function renderExample(): void {
+ container = document.createElement('div');
+ document.body.appendChild(container);
+ act(() => {
+ root = createRoot(container);
+ root.render(<UseLocaleHookUsage />);
+ });
+}
+
+afterEach(() => {
+ act(() => root?.unmount());
+ root = null;
+ container.remove();
+});
+
+describe('useLocale example', () => {
+ it('formats the invoice for English', () => {
+ renderExample();
+ expect(container.textContent).toContain('Nov 2, 2026');
+ expect(container.textContent).toContain('$1,234.50');
+ });
+
+ it('reformats the invoice when the provider locale changes to German', () => {
+ renderExample();
+ const german = Array.from(container.querySelectorAll('button')).find(
+ button => button.textContent === 'German',
+ );
+ expect(german).toBeDefined();
+ act(() => german?.click());
+ expect(container.textContent).toContain('2. Nov. 2026');
+ expect(container.textContent).toContain('1.234,50 $');
+ });
+});
diff --git a/packages/cli/assets/templates/blocks/components/Hooks/useLocaleHookUsage.doc.mjs b/packages/cli/assets/templates/blocks/components/Hooks/useLocaleHookUsage.doc.mjs
new file mode 100644
index 0000000000..8607f7893c
--- /dev/null
+++ b/packages/cli/assets/templates/blocks/components/Hooks/useLocaleHookUsage.doc.mjs
@@ -0,0 +1,20 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('@astryxdesign/cli/authoring').TemplateDoc} */
+export const doc = {
+ type: 'block',
+ exampleFor: 'useLocale',
+ name: 'useLocale — Invoice Summary',
+ displayName: 'useLocale — Invoice Summary',
+ description:
+ 'An invoice summary that formats its date and amount with Intl using the locale from useLocale, so switching the provider from English to German changes "Nov 2, 2026" and "$1,234.50" to "2. Nov. 2026" and "1.234,50 $" with no second locale source.',
+ isReady: true,
+ aspectRatio: 4 / 3,
+ componentsUsed: [
+ 'InternationalizationProvider',
+ 'Card',
+ 'SegmentedControl',
+ 'Text',
+ 'Layout',
+ ],
+};
diff --git a/packages/cli/assets/templates/blocks/components/Hooks/useLocaleHookUsage.tsx b/packages/cli/assets/templates/blocks/components/Hooks/useLocaleHookUsage.tsx
new file mode 100644
index 0000000000..39ef7cceac
--- /dev/null
+++ b/packages/cli/assets/templates/blocks/components/Hooks/useLocaleHookUsage.tsx
@@ -0,0 +1,72 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+import {useState} from 'react';
+import {Card} from '@astryxdesign/core/Card';
+import {InternationalizationProvider, useLocale} from '@astryxdesign/core/i18n';
+import {HStack, VStack} from '@astryxdesign/core/Layout';
+import {
+ SegmentedControl,
+ SegmentedControlItem,
+} from '@astryxdesign/core/SegmentedControl';
+import {Text} from '@astryxdesign/core/Text';
+
+type Locale = 'en' | 'de-DE';
+
+const ISSUED_ON = new Date(2026, 10, 2);
+const AMOUNT_DUE = 1234.5;
+
+function InvoiceSummary() {
+ const locale = useLocale();
+ const issuedOn = new Intl.DateTimeFormat(locale, {
+ day: 'numeric',
+ month: 'short',
+ year: 'numeric',
+ }).format(ISSUED_ON);
+ const amountDue = new Intl.NumberFormat(locale, {
+ style: 'currency',
+ currency: 'USD',
+ }).format(AMOUNT_DUE);
+
+ return (
+ <VStack gap={1}>
+ <HStack justify="between">
+ <Text type="body" color="secondary">
+ Issued
+ </Text>
+ <Text type="body">{issuedOn}</Text>
+ </HStack>
+ <HStack justify="between">
+ <Text type="body" color="secondary">
+ Amount due
+ </Text>
+ <Text type="body" weight="bold">
+ {amountDue}
+ </Text>
+ </HStack>
+ </VStack>
+ );
+}
+
+export default function UseLocaleHookUsage() {
+ const [locale, setLocale] = useState<Locale>('en');
+
+ return (
+ <InternationalizationProvider locale={locale}>
+ <Card width={320} padding={4}>
+ <VStack gap={3}>
+ <SegmentedControl
+ label="Language"
+ value={locale}
+ onChange={nextLocale => setLocale(nextLocale as Locale)}
+ size="sm">
+ <SegmentedControlItem value="en" label="English" />
+ <SegmentedControlItem value="de-DE" label="German" />
+ </SegmentedControl>
+ <InvoiceSummary />
+ </VStack>
+ </Card>
+ </InternationalizationProvider>
+ );
+}