Skip to content

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

TypeScript

docs(useTranslator): add a load-more footer example block (#9573)

홍규진d219cdfc64fd
diff --git a/.changeset/use-translator-load-more-example.md b/.changeset/use-translator-load-more-example.md
new file mode 100644
index 0000000000..262a3b4086
--- /dev/null
+++ b/.changeset/use-translator-load-more-example.md
@@ -0,0 +1,7 @@
+---
+'@astryxdesign/cli': patch
+---
+
+[docs] A new `useTranslator — Load More Footer` example block gets a list footer's "Load more" label and its "Showing 3 of 9" count from the function `useTranslator` returns. The app's own message keys are supplied per locale through `InternationalizationProvider`, so switching the provider to French changes both strings. Copy it with `astryx template useTranslatorHookUsage <path>`.
+
+@kyu-rong
diff --git a/apps/sandbox/scripts/next-export-routes.json b/apps/sandbox/scripts/next-export-routes.json
index 5bbe572fc5..f48084fd1b 100644
--- a/apps/sandbox/scripts/next-export-routes.json
+++ b/apps/sandbox/scripts/next-export-routes.json
@@ -786,6 +786,7 @@
"/templates/useStreamingTextHookUsage/",
"/templates/useThemeHookUsage/",
"/templates/useToastHookUsage/",
+ "/templates/useTranslatorHookUsage/",
"/templates/work-item-detail/",
"/themes/",
"/tools/"
diff --git a/internal/shadcn-registry/routes.lock.json b/internal/shadcn-registry/routes.lock.json
index 986235a580..db72ccce2c 100644
--- a/internal/shadcn-registry/routes.lock.json
+++ b/internal/shadcn-registry/routes.lock.json
@@ -3734,6 +3734,11 @@
"path": "examples/use-toast/settings-saved",
"aliases": []
},
+ {
+ "name": "example-use-translator-load-more-footer",
+ "path": "examples/use-translator/load-more-footer",
+ "aliases": []
+ },
{
"name": "example-v-stack-basic",
"path": "examples/v-stack/basic",
diff --git a/packages/cli/api/template/use-translator-hook-usage.test.tsx b/packages/cli/api/template/use-translator-hook-usage.test.tsx
new file mode 100644
index 0000000000..6edcdb5b1d
--- /dev/null
+++ b/packages/cli/api/template/use-translator-hook-usage.test.tsx
@@ -0,0 +1,74 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+// @vitest-environment jsdom
+
+/**
+ * The useTranslator example takes its button label and its count text from
+ * the translator, so both follow the provider locale and the count follows
+ * the rows shown.
+ */
+
+import {act} from 'react';
+import {createRoot, type Root} from 'react-dom/client';
+import {afterEach, describe, expect, it} from 'vitest';
+import UseTranslatorHookUsage from '../../assets/templates/blocks/components/Hooks/useTranslatorHookUsage';
+
+(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(<UseTranslatorHookUsage />);
+ });
+}
+
+function button(label: string): HTMLButtonElement {
+ const match = Array.from(
+ container.querySelectorAll<HTMLButtonElement>('button'),
+ ).find(candidate => candidate.textContent === label);
+ if (match == null) {
+ throw new Error(`no "${label}" button rendered`);
+ }
+ return match;
+}
+
+function rowCount(): number {
+ return container.querySelectorAll('li').length;
+}
+
+afterEach(() => {
+ act(() => root?.unmount());
+ root = null;
+ container.remove();
+});
+
+describe('useTranslator example', () => {
+ it('shows the English label and count, and updates the count on Load more', () => {
+ renderExample();
+ expect(rowCount()).toBe(3);
+ expect(container.textContent).toContain('Showing 3 of 9');
+
+ act(() => button('Load more').click());
+ expect(rowCount()).toBe(6);
+ expect(container.textContent).toContain('Showing 6 of 9');
+
+ act(() => button('Load more').click());
+ expect(rowCount()).toBe(9);
+ expect(container.textContent).toContain('Showing 9 of 9');
+ });
+
+ it('shows the French label and count when the provider locale changes', () => {
+ renderExample();
+ act(() => button('Load more').click());
+ act(() => button('Français').click());
+
+ expect(button('Charger plus')).toBeDefined();
+ expect(container.textContent).toContain('6 sur 9 affichées');
+ expect(container.textContent).not.toContain('Load more');
+ });
+});
diff --git a/packages/cli/assets/templates/blocks/components/Hooks/useTranslatorHookUsage.doc.mjs b/packages/cli/assets/templates/blocks/components/Hooks/useTranslatorHookUsage.doc.mjs
new file mode 100644
index 0000000000..76b605ef50
--- /dev/null
+++ b/packages/cli/assets/templates/blocks/components/Hooks/useTranslatorHookUsage.doc.mjs
@@ -0,0 +1,22 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('@astryxdesign/cli/authoring').TemplateDoc} */
+export const doc = {
+ type: 'block',
+ exampleFor: 'useTranslator',
+ name: 'useTranslator — Load More Footer',
+ displayName: 'useTranslator — Load More Footer',
+ description:
+ 'A "Load more" footer under a list that gets its button label and its "Showing 3 of 9" count from the function useTranslator returns, with app message keys supplied per locale through InternationalizationProvider, so switching the provider to French changes both strings.',
+ isReady: true,
+ aspectRatio: 4 / 3,
+ componentsUsed: [
+ 'InternationalizationProvider',
+ 'Card',
+ 'SegmentedControl',
+ 'List',
+ 'Text',
+ 'Button',
+ 'Layout',
+ ],
+};
diff --git a/packages/cli/assets/templates/blocks/components/Hooks/useTranslatorHookUsage.tsx b/packages/cli/assets/templates/blocks/components/Hooks/useTranslatorHookUsage.tsx
new file mode 100644
index 0000000000..6cd2e916ca
--- /dev/null
+++ b/packages/cli/assets/templates/blocks/components/Hooks/useTranslatorHookUsage.tsx
@@ -0,0 +1,88 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+import {useState} from 'react';
+import {Button} from '@astryxdesign/core/Button';
+import {Card} from '@astryxdesign/core/Card';
+import {
+ InternationalizationProvider,
+ useTranslator,
+ type MessagesByLocale,
+} from '@astryxdesign/core/i18n';
+import {HStack, VStack} from '@astryxdesign/core/Layout';
+import {List, ListItem} from '@astryxdesign/core/List';
+import {
+ SegmentedControl,
+ SegmentedControlItem,
+} from '@astryxdesign/core/SegmentedControl';
+import {Text} from '@astryxdesign/core/Text';
+
+type Locale = 'en' | 'fr';
+
+const MESSAGES: MessagesByLocale = {
+ en: {
+ '@myapp.invoices.loadMore': {defaultMessage: 'Load more'},
+ '@myapp.invoices.showing': {
+ defaultMessage: 'Showing {shown, number} of {total, number}',
+ },
+ },
+ fr: {
+ '@myapp.invoices.loadMore': {defaultMessage: 'Charger plus'},
+ '@myapp.invoices.showing': {
+ defaultMessage: '{shown, number} sur {total, number} affichées',
+ },
+ },
+};
+
+const INVOICES = Array.from({length: 9}, (_, index) => `INV-${1001 + index}`);
+const PAGE_SIZE = 3;
+
+function InvoiceList() {
+ const translate = useTranslator();
+ const [shownCount, setShownCount] = useState(PAGE_SIZE);
+ const total = INVOICES.length;
+
+ return (
+ <VStack gap={3}>
+ <List density="compact" hasDividers>
+ {INVOICES.slice(0, shownCount).map(invoice => (
+ <ListItem key={invoice} label={invoice} />
+ ))}
+ </List>
+ <HStack gap={2} hAlign="between" vAlign="center">
+ <Text type="supporting">
+ {translate('@myapp.invoices.showing', {shown: shownCount, total})}
+ </Text>
+ <Button
+ label={translate('@myapp.invoices.loadMore')}
+ size="sm"
+ isDisabled={shownCount >= total}
+ onClick={() => setShownCount(count => count + PAGE_SIZE)}
+ />
+ </HStack>
+ </VStack>
+ );
+}
+
+export default function UseTranslatorHookUsage() {
+ const [locale, setLocale] = useState<Locale>('en');
+
+ return (
+ <InternationalizationProvider locale={locale} messages={MESSAGES}>
+ <Card width={360} 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="fr" label="Français" />
+ </SegmentedControl>
+ <InvoiceList />
+ </VStack>
+ </Card>
+ </InternationalizationProvider>
+ );
+}