diff --git a/.changeset/tidy-examples-preview.md b/.changeset/tidy-examples-preview.md new file mode 100644 index 000000000..fe3aecc57 --- /dev/null +++ b/.changeset/tidy-examples-preview.md @@ -0,0 +1,6 @@ +--- +"@tailor-platform/app-shell": patch +--- + +Replace static documentation snippets with runnable, self-contained examples for components and hooks, including forms, data tables, and AI chat. +Improve the documentation browser with grouped sidebar navigation, a global header, and a neutral preview background. diff --git a/docs-browser/package.json b/docs-browser/package.json index 0c9927e75..43c0e019d 100644 --- a/docs-browser/package.json +++ b/docs-browser/package.json @@ -6,7 +6,8 @@ "scripts": { "dev": "vite", "build": "vite build", - "type-check": "tsc --noEmit" + "type-check": "tsc --noEmit", + "test": "node --test tests/*.test.mjs" }, "dependencies": { "@tailor-platform/app-shell": "workspace:*", diff --git a/docs-browser/src/App.tsx b/docs-browser/src/App.tsx index d909b078a..cb8ad98c0 100644 --- a/docs-browser/src/App.tsx +++ b/docs-browser/src/App.tsx @@ -1,14 +1,33 @@ +import { Fragment, type ReactNode, useState } from "react"; import { + BookOpenIcon, + CodeXmlIcon, + ComponentIcon, + LayersIcon, + LightbulbIcon, + PanelsTopLeftIcon, +} from "lucide-react"; + +import { + AppearanceSwitcher, AppShell, - DefaultSidebar, defineModule, defineResource, - SidebarLayout, + GlobalHeaderLayout, + Link, + Select, + SidebarItem, + SidebarSection, + SidebarSeparator, + Text, + useAppShell, + useLocation, } from "@tailor-platform/app-shell"; import { DocPage } from "./_lib/DocPage"; import { type DocUnit, units } from "./docs"; import HomePage from "./pages/page"; +import { sectionForPath, sections } from "./sections"; // Declarative routing: the module/resource tree is derived from the same // manifest the renderer already consumes (see docs.tsx). This dogfoods the @@ -17,13 +36,13 @@ import HomePage from "./pages/page"; type Res = ReturnType; -const CATEGORY_LABEL: Record = { - guides: "Guides", - concepts: "Concepts", - components: "Components", - patterns: "Patterns", - pages: "Pages", - api: "API", +const CATEGORY_META: Record = { + guides: { title: "Guides", icon: }, + concepts: { title: "Concepts", icon: }, + components: { title: "Components", icon: }, + patterns: { title: "Patterns", icon: }, + pages: { title: "Pages", icon: }, + api: { title: "API", icon: }, }; // Sidebar order; any category not listed falls to the end alphabetically. const CATEGORY_ORDER = ["guides", "concepts", "components", "patterns", "pages", "api"]; @@ -81,16 +100,100 @@ function buildModules(): ReturnType[] { .map((category) => defineModule({ path: category, - meta: { title: CATEGORY_LABEL[category] ?? category }, + meta: CATEGORY_META[category] ?? { title: category }, resources: buildResources(byCategory.get(category) ?? []), }), ); } +const modules = buildModules(); + +function ResourceItems({ resources, basePath }: { resources: Res[]; basePath: string }) { + return resources.map((resource, index) => { + const path = `${basePath}/${resource.path}`; + return resource.subResources?.length ? ( + + {index > 0 && } + + + + + ) : ( + + ); + }); +} + +function DocsLayout() { + const { title } = useAppShell(); + const { pathname } = useLocation(); + const [selection, setSelection] = useState(() => ({ + pathname, + section: sectionForPath(pathname), + })); + + // Follow document navigation without remounting the layout and resetting the sidebar. + if (selection.pathname !== pathname) { + setSelection({ pathname, section: sectionForPath(pathname) }); + } + + return ( + + + {title} + +
+ section.label} + onValueChange={(section) => { + if (section) setSelection({ pathname, section }); + }} + > + + + + + {sections.map((section) => ( + + {section.label} + + ))} + + +
+
+ +
+ + } + sidebar={ + + {modules + .filter((module) => selection.section.categories.includes(module.path)) + .map((module, index) => ( + + {index > 0 && } + + + + + ))} + + } + /> + ); +} + const App = () => { return ( - - } /> + + ); }; diff --git a/docs-browser/src/index.css b/docs-browser/src/index.css index 21b7f6a16..5f4c2f9e5 100644 --- a/docs-browser/src/index.css +++ b/docs-browser/src/index.css @@ -1,6 +1,6 @@ @import "tailwindcss"; @import "@tailor-platform/app-shell/styles"; -@import "@tailor-platform/app-shell/themes/bloom"; +@import "./theme.css"; /* The live examples live at the repo root (docs-src/), outside this app's own tree, so Tailwind won't discover their utility classes by default. Point it at them diff --git a/docs-browser/src/sections.ts b/docs-browser/src/sections.ts new file mode 100644 index 000000000..0f7d939e6 --- /dev/null +++ b/docs-browser/src/sections.ts @@ -0,0 +1,10 @@ +export const sections = [ + { label: "Guide and Concepts", categories: ["guides", "concepts"] }, + { label: "Components and APIs", categories: ["components", "api"] }, + { label: "Patterns and Pages", categories: ["patterns", "pages"] }, +]; + +export function sectionForPath(pathname: string) { + const category = pathname.split("/")[1]; + return sections.find((section) => section.categories.includes(category)) ?? sections[0]; +} diff --git a/docs-browser/src/theme.css b/docs-browser/src/theme.css new file mode 100644 index 000000000..591f6f1dd --- /dev/null +++ b/docs-browser/src/theme.css @@ -0,0 +1,8 @@ +/* Keep the preview canvas neutral; inherit all other tokens from the default palette. */ +:root { + --background: #fff; +} + +:root.dark { + --background: #0a0a0a; +} diff --git a/docs-browser/tests/sections.test.mjs b/docs-browser/tests/sections.test.mjs new file mode 100644 index 000000000..d7472f73d --- /dev/null +++ b/docs-browser/tests/sections.test.mjs @@ -0,0 +1,35 @@ +import assert from "node:assert/strict"; +import { test } from "node:test"; + +import { sectionForPath, sections } from "../src/sections.ts"; + +test("the three sections partition all six documentation categories", () => { + assert.deepEqual( + sections.map((section) => section.categories), + [ + ["guides", "concepts"], + ["components", "api"], + ["patterns", "pages"], + ], + ); +}); + +test("document paths select their section, including nested API pages", () => { + for (const [pathname, expected] of [ + ["/guides/introduction", sections[0]], + ["/concepts/styling-theming", sections[0]], + ["/components/button", sections[1]], + ["/api/guards/hidden", sections[1]], + ["/api/router/use-location", sections[1]], + ["/patterns/form-composer", sections[2]], + ["/pages/standard-page", sections[2]], + ]) { + assert.equal(sectionForPath(pathname), expected, pathname); + } +}); + +test("home and unknown categories default to guides without partial-prefix matches", () => { + for (const pathname of ["/", "/unknown/page", "/components-extra/button", "/apiary/page"]) { + assert.equal(sectionForPath(pathname), sections[0], pathname); + } +}); diff --git a/docs-manifest.json b/docs-manifest.json index 79598ede2..e61f12412 100644 --- a/docs-manifest.json +++ b/docs-manifest.json @@ -12,10 +12,10 @@ "symbols": ["ActionPanel", "ActionPanelProps"], "hashes": { "typeSurface": "f497e4e3021d029a", - "outline": "2e5fe6fdb0636b7c", + "outline": "f5634bc87b9c9b35", "snapshot": null, - "outputMd": "03362008aa77d4cf", - "examples": "97546c5d7e75d710" + "outputMd": "1741cb78abd51827", + "examples": "03289934089b285c" } }, "activity-card": { @@ -37,10 +37,10 @@ ], "hashes": { "typeSurface": "8aa0f940fced61be", - "outline": "495a29df69d3819e", + "outline": "0acb8012d3e5db12", "snapshot": null, - "outputMd": "1a2bb081c3e34482", - "examples": "eb7ab46dc420129f" + "outputMd": "230039d9f96fd264", + "examples": "c566c6f9fd4e00f6" } }, "aggregations": { @@ -54,9 +54,9 @@ "symbols": ["Aggregation", "aggregations"], "hashes": { "typeSurface": "0c11b3ba9d3529ad", - "outline": "5cfd5048505b0913", + "outline": "e99d37770155fa5c", "snapshot": null, - "outputMd": "daf6c93e7285ee88", + "outputMd": "96c85ba79f5c64cc", "examples": null } }, @@ -65,7 +65,7 @@ "kind": "code-backed", "outline": "docs-src/components/ai-chat.docs.outline.md", "output": "docs/components/ai-chat.md", - "examples": null, + "examples": "docs-src/components/ai-chat.docs.examples.tsx", "sources": ["packages/core/src/components/ai-chat/**"], "claims": [], "symbols": [ @@ -82,10 +82,10 @@ ], "hashes": { "typeSurface": "932ff7674cc6df99", - "outline": "0d84350ee1e55312", + "outline": "9557bfd7ad2088bc", "snapshot": "39edd53bc6562561", - "outputMd": "82313d5b6fe140d2", - "examples": null + "outputMd": "008761ccc93ef0fe", + "examples": "69f4f58f039d13fa" } }, "alert": { @@ -99,10 +99,10 @@ "symbols": ["Alert", "AlertProps", "alertVariants"], "hashes": { "typeSurface": "f28bf34ae1466912", - "outline": "6138eac23571e177", + "outline": "1b9e33f32c7749d7", "snapshot": "049e72553f5b7a6f", - "outputMd": "db2c4388ca783a75", - "examples": "65d5fc73550e395a" + "outputMd": "9b237d9c19b54102", + "examples": "8d745ceb610be06d" } }, "app-shell": { @@ -144,7 +144,7 @@ "kind": "code-backed", "outline": "docs-src/components/attachment.docs.outline.md", "output": "docs/components/attachment.md", - "examples": null, + "examples": "docs-src/components/attachment.docs.examples.tsx", "sources": ["packages/core/src/components/attachment/**"], "claims": [], "symbols": [ @@ -157,10 +157,10 @@ ], "hashes": { "typeSurface": "0a9f0c3f82e57e02", - "outline": "66aaf22c5067aef1", + "outline": "01da6dcb4ae1c2ed", "snapshot": "a5bfea8fbe1224ea", - "outputMd": "35bebce540d6ac28", - "examples": null + "outputMd": "8922f126009ee1df", + "examples": "6b3ce930e0731c54" } }, "authentication": { @@ -191,10 +191,10 @@ "symbols": ["Autocomplete", "AutocompleteAsyncFetcher"], "hashes": { "typeSurface": "81040ce8342602bc", - "outline": "b8d3f69b4adc4f13", + "outline": "e6035c4afb635461", "snapshot": "dbd3c11b7dab615d", - "outputMd": "bd6ae01bf39d1ad6", - "examples": "63e2a53825a527a4" + "outputMd": "f3179004d35f8c88", + "examples": "ad7c86260bdea0da" } }, "avatar": { @@ -208,10 +208,10 @@ "symbols": ["Avatar", "AvatarProps", "avatarVariants"], "hashes": { "typeSurface": "d6ee5e809e0f0590", - "outline": "e368c9ff0db15bb3", + "outline": "950cc8784ca1a16f", "snapshot": "ef0699939dd47de5", - "outputMd": "a874b74c176bcb47", - "examples": "009005eeac70961d" + "outputMd": "1a98b46e63c2cf7c", + "examples": "5de32d52039cd035" } }, "badge": { @@ -225,10 +225,10 @@ "symbols": ["Badge", "BadgeProps", "badgeVariants"], "hashes": { "typeSurface": "f4b8b24fb5f5bab1", - "outline": "0712a6c09e7ab542", + "outline": "0949dbd1404aa129", "snapshot": null, - "outputMd": "3d62a0fe0a539934", - "examples": "5aaa54515d4643ea" + "outputMd": "7897980baf93a074", + "examples": "e1241d5ce9845e2e" } }, "button": { @@ -242,10 +242,10 @@ "symbols": ["Button", "ButtonProps", "buttonVariants"], "hashes": { "typeSurface": "16df9927f8394548", - "outline": "200f12eb4bec959a", + "outline": "4852e242e511182e", "snapshot": "f57af2cc49c8b4d8", - "outputMd": "bce0e2fada1d1638", - "examples": "1ee01b1e27764cd2" + "outputMd": "be862b0bff15cc1a", + "examples": "4cd35b34c317297a" } }, "card": { @@ -259,10 +259,10 @@ "symbols": ["Card"], "hashes": { "typeSurface": "6ce6f0fdf2450cec", - "outline": "f76c947799dd3c05", + "outline": "95de4d29491affb3", "snapshot": "e6783ef54e17e11e", - "outputMd": "6e18faeb676654b4", - "examples": "58da87a258128f71" + "outputMd": "c1f88a287f197d79", + "examples": "7357698425183256" } }, "checkbox": { @@ -276,10 +276,10 @@ "symbols": ["Checkbox", "CheckboxProps"], "hashes": { "typeSurface": "3886bf7012f24283", - "outline": "916645fe8e5baf10", + "outline": "c6eabaf24988d251", "snapshot": "8d4d6148a3df5d61", - "outputMd": "14f7ba23f441df38", - "examples": "e8f09fba5acb116f" + "outputMd": "ebe55c40fb5fb2e6", + "examples": "afd839a3fc55cc52" } }, "combobox": { @@ -293,10 +293,10 @@ "symbols": ["Combobox", "ComboboxAsyncFetcher"], "hashes": { "typeSurface": "74ec02220321c626", - "outline": "d56abfe9595252ba", + "outline": "697f63e69aac841d", "snapshot": "6fe89974e3712977", - "outputMd": "dfb775c7c4307409", - "examples": "4c96b71b68808c66" + "outputMd": "c79cd0fe175187e3", + "examples": "ca8cc80aeca713e6" } }, "command-palette": { @@ -355,7 +355,7 @@ "kind": "code-backed", "outline": "docs-src/components/csv-importer.docs.outline.md", "output": "docs/components/csv-importer.md", - "examples": null, + "examples": "docs-src/components/csv-importer.docs.examples.tsx", "sources": ["packages/core/src/components/csv-importer/**"], "claims": [], "symbols": [ @@ -373,10 +373,10 @@ ], "hashes": { "typeSurface": "b4f7e0dc7b95af55", - "outline": "ee6b6aaae126c832", + "outline": "bc69738786edf071", "snapshot": null, - "outputMd": "53d3c795ca21b9dc", - "examples": null + "outputMd": "10c04c78bb846c9a", + "examples": "cc53461be2050a28" } }, "custom-components": { @@ -384,16 +384,16 @@ "kind": "prose", "outline": "docs-src/concepts/custom-components.docs.outline.md", "output": "docs/concepts/custom-components.md", - "examples": null, + "examples": "docs-src/concepts/custom-components.docs.examples.tsx", "sources": [], "claims": [], "symbols": [], "hashes": { "typeSurface": null, - "outline": "8668ad90672475c7", + "outline": "33a2ab998eceebef", "snapshot": null, - "outputMd": "18b8fc747d52455a", - "examples": null + "outputMd": "efba56e470f4f164", + "examples": "e11850a33b559643" } }, "data-table": { @@ -477,10 +477,10 @@ ], "hashes": { "typeSurface": "413c66caec0a0bf8", - "outline": "dc5f55408b055ba2", + "outline": "7591217822d0183b", "snapshot": "a97e067c66e46ef6", - "outputMd": "06f3ce2174fda10a", - "examples": "b94e3109d112007c" + "outputMd": "36bb587b7088fb1c", + "examples": "8adc119ac0d7152c" } }, "date-picker": { @@ -488,7 +488,7 @@ "kind": "code-backed", "outline": "docs-src/components/date-picker.docs.outline.md", "output": "docs/components/date-picker.md", - "examples": null, + "examples": "docs-src/components/date-picker.docs.examples.tsx", "sources": ["packages/core/src/components/date-field/**"], "claims": [], "symbols": [ @@ -501,10 +501,10 @@ ], "hashes": { "typeSurface": "a0f5522359e8f81d", - "outline": "adc21f4e13532e09", + "outline": "328fcaa8d2f2b6df", "snapshot": null, - "outputMd": "b7302d55df8907bc", - "examples": null + "outputMd": "376e7d4ad14c2934", + "examples": "b657b67c9745a60e" } }, "default-header": { @@ -603,10 +603,10 @@ "symbols": ["DescriptionCard", "DescriptionCardProps"], "hashes": { "typeSurface": "04d576b0cf725dfe", - "outline": "6cae471c2f101ff5", + "outline": "114ca11b5431342c", "snapshot": null, - "outputMd": "a347fd1f4ccd433e", - "examples": "8e45ff2d2e3cd59b" + "outputMd": "8930a410d7d45f89", + "examples": "a5eb77c04d06ab08" } }, "design-philosophy": { @@ -637,10 +637,10 @@ "symbols": ["Dialog"], "hashes": { "typeSurface": "b1614970f950ceb6", - "outline": "39c82f8a5f9a57d5", + "outline": "5ba9ca06b0385f80", "snapshot": "86c672f1c58f27fd", - "outputMd": "5ff9a70e8eea88dd", - "examples": "934c52d4e8761404" + "outputMd": "cd9fa9c4b8ccb108", + "examples": "f5540beaf3f36609" } }, "document-collection": { @@ -688,10 +688,10 @@ "symbols": ["DocumentProgressCard", "DocumentProgressCardProps"], "hashes": { "typeSurface": "306ea2ad2a256b8d", - "outline": "c1448e17cc81a142", + "outline": "db303752449716e0", "snapshot": "b2cfca0400f29ba0", - "outputMd": "d0fb940f685f8869", - "examples": "6962c6f28d09eb0a" + "outputMd": "cabfb86627aefd6f", + "examples": "d56bfd9ea31be76a" } }, "file-based-routing": { @@ -716,16 +716,16 @@ "kind": "code-backed", "outline": "docs-src/components/filter-rail.docs.outline.md", "output": "docs/components/filter-rail.md", - "examples": null, + "examples": "docs-src/components/filter-rail.docs.examples.tsx", "sources": ["packages/core/src/components/filter-rail/**"], "claims": [], "symbols": ["FilterRail", "FilterRailRootProps", "FilterRailSection", "useFilterRailLayout"], "hashes": { "typeSurface": "b795ce4e10be0653", - "outline": "a75520ebeae4769b", + "outline": "52990644d6ca82ab", "snapshot": "ddebbf9718587cff", - "outputMd": "224745760083ee35", - "examples": null + "outputMd": "12021e27b57f45e9", + "examples": "3d2e95eb69cb74fe" } }, "form": { @@ -733,16 +733,16 @@ "kind": "code-backed", "outline": "docs-src/components/form.docs.outline.md", "output": "docs/components/form.md", - "examples": null, + "examples": "docs-src/components/form.docs.examples.tsx", "sources": ["packages/core/src/components/form/**"], "claims": [], "symbols": ["Form", "FormProps"], "hashes": { "typeSurface": "7b374d45d53d4535", - "outline": "bb24607b4b1195e1", + "outline": "fc23844ab3a67563", "snapshot": "5d7a7904c5256f29", - "outputMd": "d14175ebbcef80fe", - "examples": null + "outputMd": "c97c3d6e426d8b29", + "examples": "c56460c1a93d532b" } }, "form-composer": { @@ -875,10 +875,10 @@ "symbols": ["Grid", "GridItemProps", "GridProps"], "hashes": { "typeSurface": "e14ecb0505a2a8bf", - "outline": "c7befb0148d5851d", + "outline": "bc138127204f0efd", "snapshot": "40fca09bec6804cf", - "outputMd": "9051eb53dde4179f", - "examples": "90bc8a3e4816a82c" + "outputMd": "d048e972ae8aba3e", + "examples": "26def49133539478" } }, "guards/hidden": { @@ -977,10 +977,10 @@ "symbols": ["Input", "InputProps"], "hashes": { "typeSurface": "7c5b64c579f508ee", - "outline": "9b273bc9e509f1fe", + "outline": "063c7293412840a2", "snapshot": "9e448d8e65418e9b", - "outputMd": "a3a6c9679af99d37", - "examples": "fc036f7af21b9dd4" + "outputMd": "876dca4c3b3bc9c5", + "examples": "72db89e4438a02c8" } }, "interaction-confirm": { @@ -1079,10 +1079,10 @@ "symbols": ["Layout", "LayoutProps"], "hashes": { "typeSurface": "c7e8fec79020d657", - "outline": "eb9cbe2aad3a08fc", + "outline": "b5f77b82d71d0eae", "snapshot": "03dedb3cc14b1eaf", - "outputMd": "638934f69a66ef12", - "examples": "3e841d9dcde141f6" + "outputMd": "3b8bf269c15e2fa5", + "examples": "c34348bb6d088ad1" } }, "menu": { @@ -1096,10 +1096,10 @@ "symbols": ["Menu"], "hashes": { "typeSurface": "943616def28cafb0", - "outline": "8f06df28129676c8", + "outline": "3cb7ee774065168f", "snapshot": "212e64b91be708c9", - "outputMd": "ceb4a05822538d20", - "examples": "cff0508bb5520ae6" + "outputMd": "05e75c52c12c3c32", + "examples": "8c07f9e1d03c5524" } }, "metric-card": { @@ -1113,10 +1113,10 @@ "symbols": ["MetricCard", "MetricCardProps"], "hashes": { "typeSurface": "a9cb24cc83f42bad", - "outline": "6e57749a9a03ca4f", + "outline": "9c6c02f7c5d9026b", "snapshot": null, - "outputMd": "5a1c557768c6590f", - "examples": "22b876f43b26922c" + "outputMd": "4742120c07f00991", + "examples": "19b8f138685f0b1a" } }, "migrations": { @@ -1175,16 +1175,16 @@ "kind": "prose", "outline": "docs-src/hooks/router/use-location.docs.outline.md", "output": "docs/api/router/use-location.md", - "examples": null, + "examples": "docs-src/hooks/router/use-location.docs.examples.tsx", "sources": [], "claims": [], "symbols": [], "hashes": { "typeSurface": null, - "outline": "c0e437bdb7348d8e", + "outline": "20888d23eb23eac1", "snapshot": null, - "outputMd": "ddb44cc51af636cc", - "examples": null + "outputMd": "ccf87add77994830", + "examples": "21dcaa18e4be0323" } }, "router/use-navigate": { @@ -1249,10 +1249,10 @@ "symbols": ["Select", "SelectAsyncFetcher"], "hashes": { "typeSurface": "429710973dfa912b", - "outline": "85a352fb834a1208", + "outline": "c542e6fc7c775d4a", "snapshot": "c7aa045d22de4cc7", - "outputMd": "e1835371d2ef76fc", - "examples": "1ce89cec30045466" + "outputMd": "7e20d26620366d82", + "examples": "260fb265390c4947" } }, "sheet": { @@ -1266,10 +1266,10 @@ "symbols": ["Sheet"], "hashes": { "typeSurface": "e760949efcbe4c38", - "outline": "5f1594d8bb39e0a5", + "outline": "3c51b0bd7cc290ab", "snapshot": "8c75bb4dad18f7b8", - "outputMd": "0f16983ba71be0bf", - "examples": "b0eebb8c5e2219dc" + "outputMd": "0be1c6430a4b7ec1", + "examples": "8f93acd2d478616f" } }, "sidebar-group": { @@ -1368,10 +1368,10 @@ "symbols": ["Spinner", "SpinnerProps"], "hashes": { "typeSurface": "cdc89a612071486c", - "outline": "4cef63f21a8c5851", + "outline": "c4418fb62a88566e", "snapshot": null, - "outputMd": "e05d94ba9c3d17da", - "examples": "19131f441efe232f" + "outputMd": "eec440408611a233", + "examples": "2782e1f9f3822dfe" } }, "styling-theming": { @@ -1385,10 +1385,10 @@ "symbols": [], "hashes": { "typeSurface": null, - "outline": "9d505cfe9358a1e7", + "outline": "c85788dd31d7e723", "snapshot": null, - "outputMd": "8a2c22e60a95b306", - "examples": "4d19f4f688e0f0ac" + "outputMd": "ba49357df367615b", + "examples": "1ea2346b99b568b7" } }, "table": { @@ -1402,10 +1402,10 @@ "symbols": ["Table"], "hashes": { "typeSurface": "bc60676f880b485b", - "outline": "9381eff2f7987a0e", + "outline": "6df1a21eb91b6fbc", "snapshot": "c788f8a131677ada", - "outputMd": "f85ec64ceb7f4acf", - "examples": "2b9d94065f2f77b7" + "outputMd": "c5933b640a78c3bf", + "examples": "d44fc86f972fd234" } }, "tabs": { @@ -1419,10 +1419,10 @@ "symbols": ["Tabs"], "hashes": { "typeSurface": "f6795191b952e110", - "outline": "833da61f24d1318a", + "outline": "f32b0cf0789281f4", "snapshot": "43ed7df4bd0f3c75", - "outputMd": "b8c595669cbe7353", - "examples": "b07f258088e81cac" + "outputMd": "a94b016f0c9709b7", + "examples": "f94b62a568ca61ee" } }, "testing": { @@ -1430,16 +1430,16 @@ "kind": "prose", "outline": "docs-src/concepts/testing.docs.outline.md", "output": "docs/concepts/testing.md", - "examples": null, + "examples": "docs-src/concepts/testing.docs.examples.tsx", "sources": [], "claims": [], "symbols": [], "hashes": { "typeSurface": null, - "outline": "e231264c4ca826e6", + "outline": "b3cb442c33cd67ca", "snapshot": null, - "outputMd": "bb713d3c7b93ad3b", - "examples": null + "outputMd": "777fd9ba9f4641f8", + "examples": "47cbf43f26e6afeb" } }, "text": { @@ -1453,10 +1453,10 @@ "symbols": ["Text", "TextProps"], "hashes": { "typeSurface": "053c8236047c6ec4", - "outline": "1441d9d6e3f5975b", + "outline": "f8366b6dd09aa48f", "snapshot": "83be7198ffac5470", - "outputMd": "24262ae6cb49a138", - "examples": "c31a669057c28ba7" + "outputMd": "e5311b1891f3ff7b", + "examples": "0e5a568ccf1638c6" } }, "textarea": { @@ -1470,10 +1470,10 @@ "symbols": ["Textarea", "TextareaProps"], "hashes": { "typeSurface": "3d9225f7356a29b2", - "outline": "40952524e46c333e", + "outline": "bf758477b779af2e", "snapshot": "c8500808c03baa29", - "outputMd": "c940bc01cd573334", - "examples": "0712ee03ad6ce259" + "outputMd": "cf324904899ed318", + "examples": "26a86dec35082a06" } }, "timeline": { @@ -1481,7 +1481,7 @@ "kind": "code-backed", "outline": "docs-src/components/timeline.docs.outline.md", "output": "docs/components/timeline.md", - "examples": null, + "examples": "docs-src/components/timeline.docs.examples.tsx", "sources": ["packages/core/src/components/timeline/**"], "claims": [], "symbols": [ @@ -1504,10 +1504,10 @@ ], "hashes": { "typeSurface": "f1d9ac66cafae3d5", - "outline": "6d4342c4015a7f33", + "outline": "76e6e33c6034cc3b", "snapshot": null, - "outputMd": "699249c9452485ab", - "examples": null + "outputMd": "5a0c1ec509b4c6dc", + "examples": "f2486bc05cde455f" } }, "toolbar": { @@ -1515,16 +1515,16 @@ "kind": "code-backed", "outline": "docs-src/components/toolbar.docs.outline.md", "output": "docs/components/toolbar.md", - "examples": null, + "examples": "docs-src/components/toolbar.docs.examples.tsx", "sources": ["packages/core/src/components/toolbar/**"], "claims": [], "symbols": ["Toolbar", "ToolbarProps"], "hashes": { "typeSurface": "2d88f0306efcaa77", - "outline": "1257a84ccd91d5c3", + "outline": "63a21fa0d305ae6d", "snapshot": "56d61f993125508c", - "outputMd": "91d70b140c7bb747", - "examples": null + "outputMd": "f8a45109e97391f5", + "examples": "fde91e48c8a1a500" } }, "tooltip": { @@ -1538,10 +1538,10 @@ "symbols": ["Tooltip"], "hashes": { "typeSurface": "d652b740db9471c7", - "outline": "eea5aed5cf4c8f33", + "outline": "6c02c292edc460ca", "snapshot": "19ed635d615f04af", - "outputMd": "113c95b2995917ed", - "examples": "87b93974e65d3a07" + "outputMd": "c3faff5e48922922", + "examples": "aadf606163c14558" } }, "tree": { @@ -1549,7 +1549,7 @@ "kind": "code-backed", "outline": "docs-src/components/tree.docs.outline.md", "output": "docs/components/tree.md", - "examples": null, + "examples": "docs-src/components/tree.docs.examples.tsx", "sources": [ "packages/core/src/components/tree/**", "packages/core/src/lib/tree/**", @@ -1569,10 +1569,10 @@ ], "hashes": { "typeSurface": "95d4d96e2c7cad05", - "outline": "6bf693a08fb6db9f", + "outline": "1044541495fff6fd", "snapshot": "e63b60420ec5113f", - "outputMd": "11c3358163ce9216", - "examples": null + "outputMd": "6010470f3c41538a", + "examples": "7e372a50c2939317" } }, "use-ai-chat": { @@ -1597,16 +1597,16 @@ "kind": "prose", "outline": "docs-src/hooks/use-app-shell.docs.outline.md", "output": "docs/api/use-app-shell.md", - "examples": null, + "examples": "docs-src/hooks/use-app-shell.docs.examples.tsx", "sources": [], "claims": [], "symbols": [], "hashes": { "typeSurface": null, - "outline": "f007ab6a89ba165d", + "outline": "9fc0b4f43e702ebc", "snapshot": null, - "outputMd": "2a73bb3f3fe1a802", - "examples": null + "outputMd": "18f76736141a6cf5", + "examples": "f70172b3ffe4a317" } }, "use-app-shell-config": { @@ -1614,16 +1614,16 @@ "kind": "prose", "outline": "docs-src/hooks/use-app-shell-config.docs.outline.md", "output": "docs/api/use-app-shell-config.md", - "examples": null, + "examples": "docs-src/hooks/use-app-shell-config.docs.examples.tsx", "sources": [], "claims": [], "symbols": [], "hashes": { "typeSurface": null, - "outline": "5ed94544ff0df649", + "outline": "e9d8c057d07d752d", "snapshot": null, - "outputMd": "42363ef05098768c", - "examples": null + "outputMd": "fda8a8d0359561dd", + "examples": "2de13d7a01e94807" } }, "use-app-shell-data": { @@ -1716,16 +1716,16 @@ "kind": "prose", "outline": "docs-src/hooks/use-resolved-locale.docs.outline.md", "output": "docs/api/use-resolved-locale.md", - "examples": null, + "examples": "docs-src/hooks/use-resolved-locale.docs.examples.tsx", "sources": [], "claims": [], "symbols": [], "hashes": { "typeSurface": null, - "outline": "d27723b34eaeb8f1", + "outline": "7eae85afc3b3262d", "snapshot": null, - "outputMd": "d0eb9f125c314d85", - "examples": null + "outputMd": "eb5e8371ba10d771", + "examples": "5f231ea108de7aab" } }, "use-route-error": { @@ -1750,16 +1750,16 @@ "kind": "prose", "outline": "docs-src/hooks/use-theme.docs.outline.md", "output": "docs/api/use-theme.md", - "examples": null, + "examples": "docs-src/hooks/use-theme.docs.examples.tsx", "sources": [], "claims": [], "symbols": [], "hashes": { "typeSurface": null, - "outline": "764717d219c6a9fc", + "outline": "a03f681bf17dc2bf", "snapshot": null, - "outputMd": "c338022de386d5e4", - "examples": null + "outputMd": "000e2603cef83d47", + "examples": "c2942d679a2b5ee3" } }, "use-time-zone": { @@ -1767,16 +1767,16 @@ "kind": "prose", "outline": "docs-src/hooks/use-time-zone.docs.outline.md", "output": "docs/api/use-time-zone.md", - "examples": null, + "examples": "docs-src/hooks/use-time-zone.docs.examples.tsx", "sources": [], "claims": [], "symbols": [], "hashes": { "typeSurface": null, - "outline": "44c8aac9cb791bd9", + "outline": "c6a62197af16b977", "snapshot": null, - "outputMd": "aaf63f2f33d6665e", - "examples": null + "outputMd": "717d6989930fb8c8", + "examples": "b081c0e5992140e1" } }, "use-toast": { @@ -1784,16 +1784,16 @@ "kind": "prose", "outline": "docs-src/hooks/use-toast.docs.outline.md", "output": "docs/api/use-toast.md", - "examples": null, + "examples": "docs-src/hooks/use-toast.docs.examples.tsx", "sources": [], "claims": [], "symbols": [], "hashes": { "typeSurface": null, - "outline": "6b730cf39dcfa154", + "outline": "9100b0606aa15761", "snapshot": null, - "outputMd": "30983a761bc61593", - "examples": null + "outputMd": "3f763c8074704709", + "examples": "0dce35625d5e56cf" } }, "with-guard": { @@ -1801,78 +1801,78 @@ "kind": "code-backed", "outline": "docs-src/components/with-guard.docs.outline.md", "output": "docs/components/with-guard.md", - "examples": null, + "examples": "docs-src/components/with-guard.docs.examples.tsx", "sources": ["packages/core/src/components/with-guard/**"], "claims": [], "symbols": ["WithGuard", "WithGuardProps"], "hashes": { "typeSurface": "82ec0e51747a308b", - "outline": "2cf6d6a02b0e3585", + "outline": "08d12a02e669b491", "snapshot": null, - "outputMd": "8d4fc931339d9a3f", - "examples": null + "outputMd": "86bb46eae81feb56", + "examples": "413511111014e7b6" } } }, "skill": { "packages/core/skills/app-shell-patterns/references/concepts/authentication.md": "a3f7aa913d59fdd7", - "packages/core/skills/app-shell-patterns/references/concepts/custom-components.md": "18b8fc747d52455a", + "packages/core/skills/app-shell-patterns/references/concepts/custom-components.md": "efba56e470f4f164", "packages/core/skills/app-shell-patterns/references/concepts/file-based-routing.md": "e189f95dbe4b0286", "packages/core/skills/app-shell-patterns/references/concepts/graphql.md": "0acfb736bcf90eff", "packages/core/skills/app-shell-patterns/references/concepts/modules-and-resources.md": "bf15b5460f22d165", "packages/core/skills/app-shell-patterns/references/concepts/routing-navigation.md": "225fb6e2b1efa4f6", "packages/core/skills/app-shell-patterns/references/concepts/sidebar-navigation.md": "5a3c8bac248061f9", - "packages/core/skills/app-shell-patterns/references/concepts/styling-theming.md": "8a2c22e60a95b306", - "packages/core/skills/app-shell-patterns/references/concepts/testing.md": "bb713d3c7b93ad3b", - "packages/core/skills/app-shell-patterns/references/components/action-panel.md": "03362008aa77d4cf", - "packages/core/skills/app-shell-patterns/references/components/activity-card.md": "1a2bb081c3e34482", - "packages/core/skills/app-shell-patterns/references/components/ai-chat.md": "82313d5b6fe140d2", - "packages/core/skills/app-shell-patterns/references/components/alert.md": "db2c4388ca783a75", + "packages/core/skills/app-shell-patterns/references/concepts/styling-theming.md": "ba49357df367615b", + "packages/core/skills/app-shell-patterns/references/concepts/testing.md": "777fd9ba9f4641f8", + "packages/core/skills/app-shell-patterns/references/components/action-panel.md": "1741cb78abd51827", + "packages/core/skills/app-shell-patterns/references/components/activity-card.md": "230039d9f96fd264", + "packages/core/skills/app-shell-patterns/references/components/ai-chat.md": "008761ccc93ef0fe", + "packages/core/skills/app-shell-patterns/references/components/alert.md": "9b237d9c19b54102", "packages/core/skills/app-shell-patterns/references/components/app-shell.md": "cd57abd4909118a4", "packages/core/skills/app-shell-patterns/references/components/appearance-switcher.md": "b55f1d538651d467", - "packages/core/skills/app-shell-patterns/references/components/attachment.md": "35bebce540d6ac28", - "packages/core/skills/app-shell-patterns/references/components/autocomplete.md": "bd6ae01bf39d1ad6", - "packages/core/skills/app-shell-patterns/references/components/avatar.md": "a874b74c176bcb47", - "packages/core/skills/app-shell-patterns/references/components/badge.md": "3d62a0fe0a539934", - "packages/core/skills/app-shell-patterns/references/components/button.md": "bce0e2fada1d1638", - "packages/core/skills/app-shell-patterns/references/components/card.md": "6e18faeb676654b4", - "packages/core/skills/app-shell-patterns/references/components/checkbox.md": "14f7ba23f441df38", - "packages/core/skills/app-shell-patterns/references/components/combobox.md": "dfb775c7c4307409", + "packages/core/skills/app-shell-patterns/references/components/attachment.md": "8922f126009ee1df", + "packages/core/skills/app-shell-patterns/references/components/autocomplete.md": "f3179004d35f8c88", + "packages/core/skills/app-shell-patterns/references/components/avatar.md": "1a98b46e63c2cf7c", + "packages/core/skills/app-shell-patterns/references/components/badge.md": "7897980baf93a074", + "packages/core/skills/app-shell-patterns/references/components/button.md": "be862b0bff15cc1a", + "packages/core/skills/app-shell-patterns/references/components/card.md": "c1f88a287f197d79", + "packages/core/skills/app-shell-patterns/references/components/checkbox.md": "ebe55c40fb5fb2e6", + "packages/core/skills/app-shell-patterns/references/components/combobox.md": "c79cd0fe175187e3", "packages/core/skills/app-shell-patterns/references/components/command-palette.md": "7e5bc675a593791a", - "packages/core/skills/app-shell-patterns/references/components/csv-importer.md": "53d3c795ca21b9dc", - "packages/core/skills/app-shell-patterns/references/components/data-table.md": "06f3ce2174fda10a", - "packages/core/skills/app-shell-patterns/references/components/date-picker.md": "b7302d55df8907bc", + "packages/core/skills/app-shell-patterns/references/components/csv-importer.md": "10c04c78bb846c9a", + "packages/core/skills/app-shell-patterns/references/components/data-table.md": "36bb587b7088fb1c", + "packages/core/skills/app-shell-patterns/references/components/date-picker.md": "376e7d4ad14c2934", "packages/core/skills/app-shell-patterns/references/components/default-header.md": "375e55f4b12fa2be", "packages/core/skills/app-shell-patterns/references/components/default-sidebar.md": "9b1672c71b6db3ff", - "packages/core/skills/app-shell-patterns/references/components/description-card.md": "a347fd1f4ccd433e", - "packages/core/skills/app-shell-patterns/references/components/dialog.md": "5ff9a70e8eea88dd", - "packages/core/skills/app-shell-patterns/references/components/document-progress-card.md": "d0fb940f685f8869", - "packages/core/skills/app-shell-patterns/references/components/filter-rail.md": "224745760083ee35", - "packages/core/skills/app-shell-patterns/references/components/form.md": "d14175ebbcef80fe", + "packages/core/skills/app-shell-patterns/references/components/description-card.md": "8930a410d7d45f89", + "packages/core/skills/app-shell-patterns/references/components/dialog.md": "cd9fa9c4b8ccb108", + "packages/core/skills/app-shell-patterns/references/components/document-progress-card.md": "cabfb86627aefd6f", + "packages/core/skills/app-shell-patterns/references/components/filter-rail.md": "12021e27b57f45e9", + "packages/core/skills/app-shell-patterns/references/components/form.md": "c97c3d6e426d8b29", "packages/core/skills/app-shell-patterns/references/components/global-header-layout.md": "fe86450720c4d586", - "packages/core/skills/app-shell-patterns/references/components/grid.md": "9051eb53dde4179f", - "packages/core/skills/app-shell-patterns/references/components/input.md": "a3a6c9679af99d37", + "packages/core/skills/app-shell-patterns/references/components/grid.md": "d048e972ae8aba3e", + "packages/core/skills/app-shell-patterns/references/components/input.md": "876dca4c3b3bc9c5", "packages/core/skills/app-shell-patterns/references/components/item-list.md": "0190e797cd8ed318", - "packages/core/skills/app-shell-patterns/references/components/layout.md": "638934f69a66ef12", - "packages/core/skills/app-shell-patterns/references/components/menu.md": "ceb4a05822538d20", - "packages/core/skills/app-shell-patterns/references/components/metric-card.md": "5a1c557768c6590f", - "packages/core/skills/app-shell-patterns/references/components/select.md": "e1835371d2ef76fc", - "packages/core/skills/app-shell-patterns/references/components/sheet.md": "0f16983ba71be0bf", + "packages/core/skills/app-shell-patterns/references/components/layout.md": "3b8bf269c15e2fa5", + "packages/core/skills/app-shell-patterns/references/components/menu.md": "05e75c52c12c3c32", + "packages/core/skills/app-shell-patterns/references/components/metric-card.md": "4742120c07f00991", + "packages/core/skills/app-shell-patterns/references/components/select.md": "7e20d26620366d82", + "packages/core/skills/app-shell-patterns/references/components/sheet.md": "0be1c6430a4b7ec1", "packages/core/skills/app-shell-patterns/references/components/sidebar-group.md": "370eccb532278bd1", "packages/core/skills/app-shell-patterns/references/components/sidebar-item.md": "9236c03e53aa79f2", "packages/core/skills/app-shell-patterns/references/components/sidebar-layout.md": "af971809e42dfdb8", "packages/core/skills/app-shell-patterns/references/components/sidebar-section.md": "281cfa2dcbff14be", - "packages/core/skills/app-shell-patterns/references/components/spinner.md": "e05d94ba9c3d17da", - "packages/core/skills/app-shell-patterns/references/components/table.md": "f85ec64ceb7f4acf", - "packages/core/skills/app-shell-patterns/references/components/tabs.md": "b8c595669cbe7353", - "packages/core/skills/app-shell-patterns/references/components/text.md": "24262ae6cb49a138", - "packages/core/skills/app-shell-patterns/references/components/textarea.md": "c940bc01cd573334", - "packages/core/skills/app-shell-patterns/references/components/timeline.md": "699249c9452485ab", - "packages/core/skills/app-shell-patterns/references/components/toolbar.md": "91d70b140c7bb747", - "packages/core/skills/app-shell-patterns/references/components/tooltip.md": "113c95b2995917ed", - "packages/core/skills/app-shell-patterns/references/components/tree.md": "11c3358163ce9216", - "packages/core/skills/app-shell-patterns/references/components/with-guard.md": "8d4fc931339d9a3f", - "packages/core/skills/app-shell-patterns/references/api/aggregations.md": "daf6c93e7285ee88", + "packages/core/skills/app-shell-patterns/references/components/spinner.md": "eec440408611a233", + "packages/core/skills/app-shell-patterns/references/components/table.md": "c5933b640a78c3bf", + "packages/core/skills/app-shell-patterns/references/components/tabs.md": "a94b016f0c9709b7", + "packages/core/skills/app-shell-patterns/references/components/text.md": "e5311b1891f3ff7b", + "packages/core/skills/app-shell-patterns/references/components/textarea.md": "cf324904899ed318", + "packages/core/skills/app-shell-patterns/references/components/timeline.md": "5a0c1ec509b4c6dc", + "packages/core/skills/app-shell-patterns/references/components/toolbar.md": "f8a45109e97391f5", + "packages/core/skills/app-shell-patterns/references/components/tooltip.md": "c3faff5e48922922", + "packages/core/skills/app-shell-patterns/references/components/tree.md": "6010470f3c41538a", + "packages/core/skills/app-shell-patterns/references/components/with-guard.md": "86bb46eae81feb56", + "packages/core/skills/app-shell-patterns/references/api/aggregations.md": "96c85ba79f5c64cc", "packages/core/skills/app-shell-patterns/references/api/create-ai-gateway-client.md": "ed0db6372d25e2f9", "packages/core/skills/app-shell-patterns/references/api/create-typed-paths.md": "4c3a858d3eb02a2a", "packages/core/skills/app-shell-patterns/references/api/define-i18n-labels.md": "3035dea9ac31b7f5", @@ -1882,22 +1882,22 @@ "packages/core/skills/app-shell-patterns/references/api/guards/overview.md": "bc694f0965c1d049", "packages/core/skills/app-shell-patterns/references/api/guards/pass.md": "3363ac1c6a7905f8", "packages/core/skills/app-shell-patterns/references/api/guards/redirect-to.md": "1b08b8aa0d013dc7", - "packages/core/skills/app-shell-patterns/references/api/router/use-location.md": "ddb44cc51af636cc", + "packages/core/skills/app-shell-patterns/references/api/router/use-location.md": "ccf87add77994830", "packages/core/skills/app-shell-patterns/references/api/router/use-navigate.md": "d018cb13a7ddc38b", "packages/core/skills/app-shell-patterns/references/api/router/use-params.md": "78c15519a8339ebb", "packages/core/skills/app-shell-patterns/references/api/use-ai-chat.md": "3bcaceab3290ca92", - "packages/core/skills/app-shell-patterns/references/api/use-app-shell.md": "2a73bb3f3fe1a802", - "packages/core/skills/app-shell-patterns/references/api/use-app-shell-config.md": "42363ef05098768c", + "packages/core/skills/app-shell-patterns/references/api/use-app-shell.md": "18f76736141a6cf5", + "packages/core/skills/app-shell-patterns/references/api/use-app-shell-config.md": "fda8a8d0359561dd", "packages/core/skills/app-shell-patterns/references/api/use-app-shell-data.md": "2ad40b17e578246d", "packages/core/skills/app-shell-patterns/references/api/use-auth.md": "7573794b872af4c8", "packages/core/skills/app-shell-patterns/references/api/use-override-breadcrumb.md": "6ec55fc3dfd8c21d", "packages/core/skills/app-shell-patterns/references/api/use-page-meta.md": "f988bdc0fb180f0c", "packages/core/skills/app-shell-patterns/references/api/use-register-command-palette-actions.md": "7144ae3dc68aa65b", - "packages/core/skills/app-shell-patterns/references/api/use-resolved-locale.md": "d0eb9f125c314d85", + "packages/core/skills/app-shell-patterns/references/api/use-resolved-locale.md": "eb5e8371ba10d771", "packages/core/skills/app-shell-patterns/references/api/use-route-error.md": "1a44180ec84ce4b9", - "packages/core/skills/app-shell-patterns/references/api/use-theme.md": "c338022de386d5e4", - "packages/core/skills/app-shell-patterns/references/api/use-time-zone.md": "aaf63f2f33d6665e", - "packages/core/skills/app-shell-patterns/references/api/use-toast.md": "30983a761bc61593", + "packages/core/skills/app-shell-patterns/references/api/use-theme.md": "000e2603cef83d47", + "packages/core/skills/app-shell-patterns/references/api/use-time-zone.md": "717d6989930fb8c8", + "packages/core/skills/app-shell-patterns/references/api/use-toast.md": "3f763c8074704709", "packages/core/skills/app-shell-patterns/references/patterns/form-composer.md": "ed187ac3a0773d3d", "packages/core/skills/app-shell-patterns/references/patterns/form-modal.md": "a0d3c952b0b10351", "packages/core/skills/app-shell-patterns/references/patterns/form-sectioned.md": "d31cd3ae6ad0790c", diff --git a/docs-src/components/action-panel.docs.examples.tsx b/docs-src/components/action-panel.docs.examples.tsx index acc5e578d..12a8add8d 100644 --- a/docs-src/components/action-panel.docs.examples.tsx +++ b/docs-src/components/action-panel.docs.examples.tsx @@ -1,5 +1,6 @@ +import { useEffect, useState } from "react"; import { ActionPanel, Text } from "@tailor-platform/app-shell"; -import { ExternalLink, Receipt } from "lucide-react"; +import { Check, ExternalLink, Receipt } from "lucide-react"; export function BasicUsage() { return ( @@ -23,6 +24,48 @@ export function BasicUsage() { ); } +export function WithLoadingState() { + const [loadingKey, setLoadingKey] = useState(null); + const [confirmed, setConfirmed] = useState(false); + + useEffect(() => { + if (loadingKey !== "confirm") return; + + const timer = setTimeout(() => { + setConfirmed(true); + setLoadingKey(null); + }, 1000); + return () => clearTimeout(timer); + }, [loadingKey]); + + return ( +
+ , + onClick: () => { + setConfirmed(false); + setLoadingKey("confirm"); + }, + loading: loadingKey === "confirm", + }, + ]} + /> + + {loadingKey === "confirm" + ? "Confirming order…" + : confirmed + ? "Order SO-1001 confirmed. You can try again." + : "Click Confirm order to simulate a request."} + +
+ ); +} + export function CustomEmptyContent() { return ( @@ -52,33 +54,9 @@ Pass `null` to hide the empty content and its additional vertical spacing while ## With Loading State -Use parent state to control which row is loading: - -```tsx -const [loadingKey, setLoadingKey] = useState(null); - -const handleConfirm = async () => { - setLoadingKey("confirm"); - try { - await confirmOrder(orderId); - } finally { - setLoadingKey(null); - } -}; +Use parent state to control which row is loading. This example simulates confirmation with a one-second timer, which is cleaned up when the example unmounts. Click again after completion to repeat it. For a real request, set the loading key before awaiting it and clear it in `finally`. -, - onClick: handleConfirm, - loading: loadingKey === "confirm", - }, - ]} -/>; -``` + ## CommandPalette Integration diff --git a/docs-src/components/activity-card.docs.examples.tsx b/docs-src/components/activity-card.docs.examples.tsx index 0318f22cf..4cea392c0 100644 --- a/docs-src/components/activity-card.docs.examples.tsx +++ b/docs-src/components/activity-card.docs.examples.tsx @@ -1,4 +1,5 @@ -import { ActivityCard } from "@tailor-platform/app-shell"; +import { CheckCircle } from "lucide-react"; +import { ActivityCard, Text, type ActivityCardBaseItem } from "@tailor-platform/app-shell"; const items = [ { @@ -23,3 +24,91 @@ const items = [ export function BasicUsage() { return ; } + +export function OverflowAndDialog() { + const descriptions = [ + "sent the order confirmation", + "confirmed the order", + "approved the order", + "updated the delivery date", + "added a note", + "changed the shipping address", + "added a line item", + "created the order", + ]; + const items = descriptions.map((description, index) => ({ + id: String(index), + actor: { name: index % 2 === 0 ? "Avery" : "Morgan" }, + description, + timestamp: new Date(2026, 2, 21, 17 - index), + })); + + return ; +} + +export function GroupingByDay() { + const today = new Date(); + const yesterday = new Date(today); + yesterday.setDate(yesterday.getDate() - 1); + const earlier = new Date(today); + earlier.setDate(earlier.getDate() - 3); + + const items = [ + { + id: "confirmed", + actor: { name: "Avery" }, + description: "confirmed the order", + timestamp: today, + }, + { + id: "updated", + actor: { name: "Morgan" }, + description: "updated the delivery date", + timestamp: yesterday, + }, + { + id: "created", + actor: { name: "Avery" }, + description: "created the order", + timestamp: earlier, + }, + ]; + + return ; +} + +export function CompoundItems() { + interface MyItem extends ActivityCardBaseItem { + kind: "approval" | "update"; + label?: string; + message?: string; + } + + const items: MyItem[] = [ + { id: "1", timestamp: "2026-03-21T09:00:00", kind: "approval", label: "PO approved" }, + { + id: "2", + timestamp: "2026-03-20T15:00:00", + kind: "update", + message: "Status changed to CONFIRMED", + }, + ]; + + return ( + + > + {(item) => + item.kind === "approval" ? ( + }> + {item.label} + + ) : ( + + {item.message} + + ) + } + + + ); +} diff --git a/docs-src/components/activity-card.docs.outline.md b/docs-src/components/activity-card.docs.outline.md index cd666b825..1f194ba0b 100644 --- a/docs-src/components/activity-card.docs.outline.md +++ b/docs-src/components/activity-card.docs.outline.md @@ -22,6 +22,8 @@ import { } from "@tailor-platform/app-shell"; ``` +The examples below also import `Text` from `@tailor-platform/app-shell` and `CheckCircle` from `lucide-react`. + Use `ActivityCardItem` for each item in the standalone API. Use `ActivityCardBaseItem` as the minimum constraint when extending items for the compound API. ## Basic Usage @@ -32,18 +34,15 @@ Use `ActivityCardItem` for each item in the standalone API. Use `ActivityCardBas By default the card shows the 6 most recent activities. If there are more, a button appears at the bottom (e.g. **"2 more activities"**). Clicking it opens a modal dialog titled "All activities" with the full list in a scrollable area. The overflow label can be switched to a count style (**"+2"**) via the `overflowLabel` prop. -```tsx - -// or overflowLabel="count" for "+N" -``` + ## Grouping by day Set `groupBy="day"` to group activities under labels like "TODAY", "YESTERDAY", or a formatted date. -```tsx - -``` +The example uses dates relative to today so all three labels remain visible as time passes. + + ## Props @@ -100,36 +99,7 @@ import { ActivityCard, type ActivityCardBaseItem } from "@tailor-platform/app-sh ### Example -```tsx -import { ActivityCard, Text, type ActivityCardBaseItem } from "@tailor-platform/app-shell"; - -interface MyItem extends ActivityCardBaseItem { - kind: "approval" | "update"; - label?: string; - message?: string; -} - -const items: MyItem[] = [ - { id: "1", timestamp: new Date(), kind: "approval", label: "PO approved" }, - { id: "2", timestamp: new Date(), kind: "update", message: "Status changed to CONFIRMED" }, -]; - - - > - {(item) => - item.kind === "approval" ? ( - }> - {item.label} - - ) : ( - - {item.message} - - ) - } - -; -``` + --- diff --git a/docs-src/components/ai-chat.docs.examples.tsx b/docs-src/components/ai-chat.docs.examples.tsx new file mode 100644 index 000000000..9fb90af19 --- /dev/null +++ b/docs-src/components/ai-chat.docs.examples.tsx @@ -0,0 +1,438 @@ +import { useState } from "react"; +import { + ChevronsRightIcon, + CopyIcon, + EraserIcon, + HistoryIcon, + RotateCcwIcon, + SparklesIcon, + ThumbsUpIcon, +} from "lucide-react"; +import { + AIChat, + Button, + Card, + Select, + Text, + useAIChat, + type AIGatewayClient, + type ToolState, +} from "@tailor-platform/app-shell"; + +export function BasicUsage() { + const [client] = useState(() => ({ + async *streamChatCompletion({ signal }) { + const chunks = [ + "This is a **local demo response**.", + "\n\n", + "The real `useAIChat()` hook ", + "manages this conversation ", + "and receives these chunks ", + "from an in-memory client.", + "\n\n", + "No prompt is sent to a server. ", + "Send another message, ", + "or press **Stop** while the response is streaming.", + ]; + for (const text of chunks) { + if (signal?.aborted) return; + // Delay fixture chunks so streaming and Stop can be tried without a server. + await new Promise((resolve) => setTimeout(resolve, 180)); + if (signal?.aborted) return; + yield { type: "text-delta", text }; + } + yield { type: "done" }; + }, + })); + const { messages, status, error, sendMessage, stop } = useAIChat({ client, model: "demo" }); + + return ( +
+ {error && {error.message}} + + + + + {messages.length === 0 ? ( + + ) : ( + messages.map((message) => ( + + {message.content} + + )) + )} + + + + +
+ ); +} + +export function HeaderActions() { + const [collapsed, setCollapsed] = useState(false); + const [showHistory, setShowHistory] = useState(false); + const [message, setMessage] = useState("Your purchase order is ready for review."); + + if (collapsed) return ; + + return ( + + + setCollapsed(true)}> + + + } + actions={ + <> + setShowHistory((value) => !value)} + > + + + { + setMessage(""); + setShowHistory(false); + }} + > + + + + } + /> + + {showHistory ? ( + + ) : message ? ( + + {message} + + ) : ( + + )} + + + + ); +} + +export function EmptyStateSuggestions() { + const [prompt, setPrompt] = useState(null); + + return ( + + + setPrompt(null)}> + + + } + /> + + {prompt === null ? ( + } + title="Ask the assistant" + description="Choose a starter prompt. No request is sent." + > + + + + + + ) : ( + <> + + {prompt} + + + + This predefined local reply shows where an application would render the answer. + + + + )} + + + + ); +} + +export function MessageActions() { + const [revision, setRevision] = useState(1); + const [feedback, setFeedback] = useState("No action selected."); + const response = `Summary revision ${revision}: three orders are ready for review.`; + + async function copyResponse() { + try { + await navigator.clipboard.writeText(response); + setFeedback("Response copied."); + } catch { + setFeedback("Clipboard access is unavailable. Select the response text to copy it manually."); + } + } + + return ( +
+ + {response} + + void copyResponse()}> + + + { + setRevision((value) => value + 1); + setFeedback("Generated another local revision."); + }} + > + + + setFeedback("Marked helpful.")} + > + + + + + {feedback} +
+ ); +} + +export function ActiveToolCalls() { + const [active, setActive] = useState(true); + const calls = [ + { id: "search", name: "search_help_articles" }, + { id: "orders", name: "list_open_orders" }, + ]; + + return ( +
+ + + + + {active ? ( + + {calls.map((call) => ( + + ))} + + ) : ( + No active tool requests. + )} + + + + + These fixture names represent requests, not execution results. No tools are executed. + +
+ ); +} + +export function ToolLifecycle() { + const states: ToolState[] = [ + "input-streaming", + "input-available", + "output-available", + "output-error", + ]; + const [state, setState] = useState("output-available"); + + return ( +
+ { + if (value) setState(value); + }} + className="max-w-xs" + /> + + + +
+ ); +} + +export function ColumnLayout() { + type Product = { id: string; name: string; description: string; price: number; quantity: number }; + const { column } = createColumnHelper(); + const table = useDataTable({ + columns: [ + column({ id: "name", label: "Product", type: "text", width: 180, pin: "left" }), + column({ id: "description", label: "Description", type: "text", width: 280, truncate: true }), + column({ + id: "price", + label: "Unit price", + type: "money", + width: 160, + typeOptions: { currency: "USD" }, + }), + column({ id: "quantity", label: "Quantity", type: "number", width: 120, pin: "right" }), + ], + data: { + rows: [ + { + id: "1", + name: "Small carton", + description: "Recycled cardboard packaging for small shipments", + price: 2.5, + quantity: 24, + }, + { + id: "2", + name: "Large carton", + description: "Double-wall cardboard packaging for large shipments", + price: 5, + quantity: 12, + }, + ], + }, + }); + + return ( + + + + + + + + + + + ); +} + +export function Sorting() { + type Product = { id: string; name: string; quantity: number }; + const [multiple, setMultiple] = useState(false); + const { control } = useCollectionVariables({}); + const rows: Product[] = [ + { id: "1", name: "Carton", quantity: 24 }, + { id: "2", name: "Box", quantity: 12 }, + { id: "3", name: "Carton", quantity: 6 }, + ]; + const sortedRows = rows.toSorted((a, b) => { + for (const { field, direction } of control.sortStates) { + const difference = field === "name" ? a.name.localeCompare(b.name) : a.quantity - b.quantity; + if (difference) return direction === "Desc" ? -difference : difference; + } + return 0; + }); + const table = useDataTable({ + columns: [ + { id: "name", label: "Product", type: "text", sort: { field: "name", type: "string" } }, + { + id: "quantity", + label: "Quantity", + type: "number", + sort: { field: "quantity", type: "number" }, + }, + ], + data: { rows: sortedRows }, + control, + sort: { multiple }, + }); + + return ( +
+ { + setMultiple(checked); + control.clearSort(); + }} + /> + + + +
+        {JSON.stringify(table.sortStates, null, 2)}
+      
+
+ ); +} + +export function Filtering() { + type Product = { id: string; name: string; quantity: number; status: string }; + const { variables, control } = useCollectionVariables({}); + const products: Product[] = [ + { id: "1", name: "Small carton", quantity: 24, status: "Available" }, + { id: "2", name: "Large CARTON", quantity: 12, status: "Available" }, + { id: "3", name: "Storage box", quantity: 0, status: "Sold out" }, + ]; + // shortcut: evaluates only the configured demo filters, use your API for other operators. + const rows = products.filter((row) => + control.filters.every((filter) => { + if (filter.field === "name") { + const value = String(filter.value); + return filter.caseSensitive + ? row.name.includes(value) + : row.name.toLowerCase().includes(value.toLowerCase()); + } + if (filter.field === "quantity") return row.quantity >= Number(filter.value); + if (filter.field === "status") + return Array.isArray(filter.value) && filter.value.includes(row.status); + return false; + }), + ); + const table = useDataTable({ + columns: [ + { + id: "name", + label: "Product", + type: "text", + filter: { field: "name", type: "string", operators: ["contains"] }, + }, + { + id: "quantity", + label: "Quantity", + type: "number", + filter: { field: "quantity", type: "number", operators: ["gte"] }, + }, + { + id: "status", + label: "Status", + type: "badge", + filter: { + field: "status", + type: "enum", + operators: ["in"], + options: [ + { value: "Available", label: "Available" }, + { value: "Sold out", label: "Sold out" }, + ], + }, + }, + ], + data: { rows }, + control, + }); + + return ( +
+ + + + + + + + + + + + + + + + + + +
+        {JSON.stringify(variables.query ?? {}, null, 2)}
+      
+
+ ); +} + +export function Pagination() { + const { variables, control } = useCollectionVariables({ params: { pageSize: 2 } }); + const allRows = Array.from({ length: 5 }, (_, index) => ({ + id: String(index + 1), + name: `Product ${index + 1}`, + })); + const { first, after, last, before } = variables.pagination; + let start: number; + let end: number; + if (last !== undefined) { + end = before != null ? Number(before) : allRows.length; + start = Math.max(0, end - last); + } else { + start = after != null ? Number(after) + 1 : 0; + end = Math.min(allRows.length, start + (first ?? 2)); + } + const rows = allRows.slice(start, end); + const table = useDataTable({ + columns: [{ id: "name", label: "Product", type: "text" }], + control, + rowSelection: {}, + data: { + rows, + total: allRows.length, + pageInfo: { + startCursor: rows.length ? String(start) : null, + endCursor: rows.length ? String(start + rows.length - 1) : null, + hasPreviousPage: start > 0, + hasNextPage: start + rows.length < allRows.length, + }, + }, + }); + + return ( +
+ + + + + + +
+        {JSON.stringify(variables.pagination, null, 2)}
+      
+
+ ); +} + +export function MetadataFilters() { + const metadata = { + name: "request", + pluralForm: "requests", + fields: [ + { name: "amount", type: "decimal", required: false, description: "Exact amount" }, + { name: "dueDate", type: "date", required: false, description: "Due date" }, + { name: "createdAt", type: "datetime", required: false, description: "Created at" }, + { name: "reminder", type: "time", required: false, description: "Reminder" }, + { name: "active", type: "boolean", required: false, description: "Active" }, + { name: "reference", type: "uuid", required: false, description: "Reference ID" }, + ], + } as const; + const { variables, control } = useCollectionVariables({ tableMetadata: metadata }); + const { column, inferColumns } = createColumnHelper>(); + const infer = inferColumns(metadata); + const table = useDataTable({ + columns: metadata.fields.map((field) => column({ ...infer(field.name), type: "text" })), + data: undefined, + control, + }); + + return ( +
+ + Try the metadata-generated filter editors. This playground shows query variables, not + backend results. + + + + +
+        {JSON.stringify(variables.query ?? {}, null, 2)}
+      
+
+ ); +} + +export function CollectionUrlState() { + const [searchParams, setSearchParams] = useState(() => new URLSearchParams("p=2&s=title:asc")); + const { variables, control } = useCollectionVariables( + withURLCollectionState({ params: { pageSize: 2 } }, [searchParams, setSearchParams]), + ); + + return ( +
+
+ + + +
+ setName(e.target.value)} /> - - }>Cancel - - - - - ); -} -``` +Edit the item name and save to update the value outside the dialog. Empty or whitespace-only names are rejected through `Form` and `Field`. Cancel or close leaves the saved name unchanged; reopening restores it. Cancel is explicitly `type="button"` so it does not submit the form. + + ## Stacking diff --git a/docs-src/components/document-progress-card.docs.examples.tsx b/docs-src/components/document-progress-card.docs.examples.tsx index 8c52bc2c2..e4b3ba283 100644 --- a/docs-src/components/document-progress-card.docs.examples.tsx +++ b/docs-src/components/document-progress-card.docs.examples.tsx @@ -13,3 +13,68 @@ export function BasicUsage() { /> ); } + +export function CustomLegend() { + return ( + + ); +} + +export function PurchaseOrderFulfilment() { + function Fulfilment({ + received, + returned, + yetToReceive, + returnedCountsAsComplete = true, + }: { + received: number; + returned: number; + yetToReceive: number; + returnedCountsAsComplete?: boolean; + }) { + // Returned is a subset of received; clamp so the breakdown cannot exceed it. + const effectiveReturned = Math.min(Math.max(returned, 0), Math.max(received, 0)); + const total = Math.max(received, 0) + Math.max(yetToReceive, 0); + const complete = returnedCountsAsComplete ? received : received - effectiveReturned; + const percent = total > 0 ? Math.round((complete / total) * 100) : 0; + + return ( + + ); + } + + return ( +
+ + +
+ ); +} diff --git a/docs-src/components/document-progress-card.docs.outline.md b/docs-src/components/document-progress-card.docs.outline.md index a87d8fc41..0aea4dc33 100644 --- a/docs-src/components/document-progress-card.docs.outline.md +++ b/docs-src/components/document-progress-card.docs.outline.md @@ -43,67 +43,13 @@ The bar tiles `segments` left-to-right, each sized as `value / (total ?? sum of By default the legend mirrors `segments`. Pass `legend` to render different rows — for example when buckets overlap and the bar shows a decomposition while the legend shows the raw figures: -```tsx - -``` + ## Example: purchase-order fulfilment A common use is communicating a purchase order's receiving state — **received**, **returned**, and **yet to receive**. `DocumentProgressCard` stays generic, so derive the percentage and the bar breakdown in your component and pass them in. This recipe reproduces the recommended look (labels, indigo/pink/neutral colors, and a bar that decomposes received into "kept" + "returned" against the ordered total): -```tsx -function PurchaseOrderFulfilment({ - received, - returned, - yetToReceive, - // Whether returned items still count as fulfilled. Set false to subtract them. - returnedCountsAsComplete = true, -}: { - received: number; - returned: number; - yetToReceive: number; - returnedCountsAsComplete?: boolean; -}) { - // Returned is a subset of received; clamp so the breakdown can't exceed it. - const effectiveReturned = Math.min(Math.max(returned, 0), Math.max(received, 0)); - const total = Math.max(received, 0) + Math.max(yetToReceive, 0); // the ordered quantity - const complete = returnedCountsAsComplete ? received : received - effectiveReturned; - const percent = total > 0 ? Math.round((complete / total) * 100) : 0; - - return ( - - ); -} - -// → 30% -``` + Notes for adapting it: diff --git a/docs-src/components/filter-rail.docs.examples.tsx b/docs-src/components/filter-rail.docs.examples.tsx new file mode 100644 index 000000000..82bce7d78 --- /dev/null +++ b/docs-src/components/filter-rail.docs.examples.tsx @@ -0,0 +1,209 @@ +import { + Button, + DataTable, + FilterRail, + Text, + useCollectionVariables, + useDataTable, + useFilterRailLayout, + type FilterRailSection, +} from "@tailor-platform/app-shell"; + +export function BasicUsage() { + type Product = { id: string; name: string; category: string; status: string }; + const { variables, control } = useCollectionVariables({}); + const sections: FilterRailSection[] = [ + { + id: "category", + label: "Category", + control: "checkbox", + field: "category", + truncate: 2, + options: ["Packaging", "Storage", "Office"].map((value) => ({ value, label: value })), + }, + { + id: "status", + label: "Status", + control: "radio", + field: "status", + options: ["Draft", "Published"].map((value) => ({ value, label: value })), + }, + ]; + const products: Product[] = [ + { id: "1", name: "Small carton", category: "Packaging", status: "Published" }, + { id: "2", name: "Storage box", category: "Storage", status: "Draft" }, + { id: "3", name: "Desk organizer", category: "Office", status: "Published" }, + ]; + const rows = products.filter((row) => + control.filters.every((filter) => { + if (filter.field === "category") + return Array.isArray(filter.value) && filter.value.includes(row.category); + if (filter.field === "status") return row.status === filter.value; + return false; + }), + ); + const table = useDataTable({ + columns: [ + { id: "name", label: "Product", type: "text" }, + { id: "status", label: "Status", type: "badge" }, + ], + data: { rows }, + control, + }); + + return ( +
+
+ + + Clear product filters + + + +
+ + + +
+
+ Matching products: {rows.length} +
+        {JSON.stringify(variables.query ?? {}, null, 2)}
+      
+
+ ); +} + +export function SectionControls() { + const { variables, control } = useCollectionVariables({}); + const sections: FilterRailSection[] = [ + { + id: "name", + label: "Product name", + control: "text", + field: "name", + operator: "contains", + placeholder: "Search product names...", + }, + { + id: "available", + label: "Availability", + control: "boolean", + field: "available", + trueLabel: "In stock", + falseLabel: "Out of stock", + }, + { + id: "price", + label: "Price", + control: "numberRange", + field: "price", + min: 0, + step: 1, + unit: "USD", + }, + { + id: "delivery", + label: "Deliver on or after", + control: "date", + field: "delivery", + operator: "gte", + }, + { + id: "ordered", + label: "Order period", + control: "dateRange", + field: "ordered", + presets: [{ label: "April 2026", from: "2026-04-01", to: "2026-04-30" }], + }, + { + id: "stock", + label: "Custom stock filter", + control: "custom", + fields: ["stock"], + render: ({ getFilter, setFilter }) => ( + + ), + }, + ]; + + return ( +
+ + This playground shows generated query values; it does not fetch or filter records. + + + + Clear control filters + + + +
+        {JSON.stringify(variables.query ?? {}, null, 2)}
+      
+
+ ); +} + +export function LayoutAndResponsive() { + const { variables, control } = useCollectionVariables({}); + const layout = useFilterRailLayout("docs:filter-rail:layout-example"); + const sections: FilterRailSection[] = [ + { + id: "category", + label: "Category", + control: "checkbox", + field: "category", + options: ["Storage", "Office", "Packaging"].map((value) => ({ value, label: value })), + }, + { + id: "status", + label: "Status", + control: "radio", + field: "status", + options: ["Draft", "Published"].map((value) => ({ value, label: value })), + }, + { + id: "available", + label: "Availability", + control: "boolean", + field: "available", + defaultCollapsed: true, + }, + ]; + + return ( + +
+ + Use settings to hide, reorder, or sort sections. Narrow the browser below 1024px to open + the same rail in a sheet. + + Open demo filters + + + Clear layout filters + + + + +
+          {JSON.stringify({ layout: layout.value, query: variables.query ?? {} }, null, 2)}
+        
+
+
+ ); +} diff --git a/docs-src/components/filter-rail.docs.outline.md b/docs-src/components/filter-rail.docs.outline.md index 03b7ef99b..b0b15261e 100644 --- a/docs-src/components/filter-rail.docs.outline.md +++ b/docs-src/components/filter-rail.docs.outline.md @@ -13,24 +13,19 @@ sources: It writes the same `CollectionControl` a `DataTable` reads, so there is no second filter engine: a checkbox section **is** the `in` operator, a radio section is `eq`, a range is `between`. +## Import + ```tsx import { FilterRail, type FilterRailSection } from "@tailor-platform/app-shell"; +``` -const sections: FilterRailSection[] = [ - { - id: "category", - label: "Category", - control: "checkbox", - field: "category", - options: categories, - }, - { id: "status", label: "Status", control: "radio", field: "status", options: statuses }, -]; +The runnable examples also import `Button`, `DataTable`, `Text`, `useCollectionVariables`, `useDataTable`, and `useFilterRailLayout` from `@tailor-platform/app-shell`. - - -; -``` +## Basic Usage + +Choose categories and a status to filter the local product rows. The checkbox list supports search and **Show more**; each section can be collapsed without clearing its selection. **Clear product filters** restores all rows. This example evaluates only its two configured fields locally; a real application sends the derived query to its backend. There is no second `DataTable.Filters` surface for the same fields. + + ## Sections and parts @@ -46,15 +41,7 @@ What the rail shows is **config**: `sections`, one entry per axis, in screen ord | `FilterRail.Provider` | Holds the config when a `Trigger` sits outside the rail (see Narrow screens). | | `FilterRail.Trigger` | The narrow-screen "Filters" button, placed anywhere inside `Provider`. | -```tsx - - - - - - - -``` +The [layout example](#user-layout) assembles the header, clear action, settings, and sections. Leave out `Settings` when users do not need to customize the rail. ### Section types @@ -73,6 +60,10 @@ Every section has an `id`, a `label` and an optional `hint`. The operator is fix A checkbox list long enough to be truncated also gets a search box, so a value can be found without scrolling (`searchThreshold` overrides when it appears). +The following playground covers the other six section types: text, boolean, number range, date, date range, and custom. Text commits after its debounce; numeric bounds commit on blur or Enter. Try the **April 2026** preset or **Low stock: 1–20**, and inspect the generated query below. This playground generates filter values only, not backend results. + + + A field holds one filter, so two sections must not share a field; the rail warns in the console when they do. #### Typing fields @@ -88,23 +79,7 @@ const sections: FilterRailSection[] = [ With a typed control (from `useCollectionVariables({ tableMetadata })`), a section whose field the control does not have is also rejected. -```tsx -const stockLevel: FilterRailSection = { - id: "stockLevel", - label: "Stock level", - control: "custom", - fields: ["stock"], - render: ({ getFilter, setFilter }) => ( - - ), -}; -``` +The **Custom stock filter** in the playground uses `getFilter` and `setFilter` to toggle a `between` filter. Its `fields: ["stock"]` declaration makes that filter participate in **Clear all**. The rail never hides state: a selected option is never truncated away, never disabled and never hidden by a section's search box. @@ -136,6 +111,10 @@ In development the rail warns in the console when a checkbox or radio section li `useFilterRailLayout(storageKey)` persists the user's section order, hidden sections and option sort to localStorage. Pass it as `layout` and add `FilterRail.Settings`. Hiding a section that carries a filter also clears that filter. To share a layout across a team, pass your own `{ value, onChange, onReset }` binding instead. +Open settings to hide sections, sort checkbox options, or reorder sections by dragging or using the reorder handle's arrow keys. **Availability** starts collapsed. This example saves only its own preferences under the namespaced key `docs:filter-rail:layout-example`; settings' Reset restores the authored defaults. The separate **Open demo filters** trigger appears below the `lg` breakpoint, without adding application breakpoint code. + + + ## Beside a DataTable The rail sits in its own `Layout.Column`, outside `DataTable.Root`, which is why `control` is a prop. Do not also render `DataTable.Filters` for the same fields — one fact in two places can drift. @@ -146,29 +125,4 @@ Below the `lg` breakpoint there is no room for a side column, so the rail turns By default the button appears where the rail would have been. To put it somewhere else — a table toolbar, a page header — wrap the page in `FilterRail.Provider`, move the config there, and place `FilterRail.Trigger` wherever you want it. The Trigger renders nothing on wide screens, and while one is mounted the rail skips its own button. -```tsx - - - - - - - - - - - - - - - - - - - - - - - - -``` +Narrow the browser below 1024px in the [layout example](#user-layout). **Open demo filters** opens the same sections in a left sheet and shows the active count. Press Escape or click the backdrop to close it, then reopen the sheet to verify that filters and collapsed sections remain intact. The example uses `FilterRail.Provider` to share configuration with the trigger outside `Root`, without requiring any Shell layout component. diff --git a/docs-src/components/form.docs.examples.tsx b/docs-src/components/form.docs.examples.tsx new file mode 100644 index 000000000..3ba93cbb1 --- /dev/null +++ b/docs-src/components/form.docs.examples.tsx @@ -0,0 +1,200 @@ +import { useId, useRef, useState } from "react"; +import { Button, Combobox, Field, Fieldset, Form, Select, Text } from "@tailor-platform/app-shell"; + +export function BasicUsage() { + const [submitted, setSubmitted] = useState<{ email: string } | null>(null); + + return ( + + noValidate + className="max-w-sm space-y-4" + onFormSubmit={(values) => setSubmitted(values)} + > + + Email + + We'll never share your email. + Email is required. + Enter a valid email address. + + + + {submitted ? `Submitted email: ${submitted.email}` : "No email submitted yet."} + + + ); +} + +export function ExternalErrors() { + const [errors, setErrors] = useState>({}); + const [savedUrl, setSavedUrl] = useState(null); + + function handleSubmit(values: { url: string }) { + // Simulate an API validation response without sending a request. + if (values.url === "https://taken.example.com") { + setErrors({ url: "This homepage is already registered." }); + setSavedUrl(null); + return; + } + + setErrors({}); + setSavedUrl(values.url); + } + + return ( + + noValidate + errors={errors} + onFormSubmit={handleSubmit} + className="max-w-sm space-y-4" + > + + Homepage + + Try another URL after the simulated server rejection. + + + + + {savedUrl ? `Saved homepage: ${savedUrl}` : "No homepage saved yet."} + + + ); +} + +export function ProgrammaticValidation() { + const actions = useRef<{ validate: () => void }>(null); + + return ( +
+
+ + Name + + Name is required. + +
+ +
+ ); +} + +export function WithSelect() { + const [submitted, setSubmitted] = useState<{ country: string } | null>(null); + + return ( + + noValidate + className="max-w-sm space-y-4" + onFormSubmit={(values) => setSubmitted(values)} + > + + Country + ` props they don't take. `Field.Control` logs a console warning when it is given one of these controls directly as an element. A wrapper component or the function form of `render` is not detected. -```tsx -const [country, setCountry] = React.useState(null); - - - Country - ; } + +export function TextInput() { + return ; +} + +export function EmailInput() { + return ; +} + +export function NumberInput() { + return ; +} + +export function DisabledInput() { + return ; +} diff --git a/docs-src/components/input.docs.outline.md b/docs-src/components/input.docs.outline.md index f35710773..06a32e104 100644 --- a/docs-src/components/input.docs.outline.md +++ b/docs-src/components/input.docs.outline.md @@ -36,27 +36,19 @@ Accepts all standard HTML `` props. ### Text Input -```tsx - -``` + ### Email Input -```tsx - -``` + ### Number Input -```tsx - -``` + ### Disabled Input -```tsx - -``` + ### With onChange Handler diff --git a/docs-src/components/layout.docs.examples.tsx b/docs-src/components/layout.docs.examples.tsx index e469dcec1..faba0b2ec 100644 --- a/docs-src/components/layout.docs.examples.tsx +++ b/docs-src/components/layout.docs.examples.tsx @@ -1,4 +1,4 @@ -import { Layout, Text } from "@tailor-platform/app-shell"; +import { Button, Layout, Text } from "@tailor-platform/app-shell"; export function BasicUsage() { return ( @@ -14,3 +14,109 @@ export function BasicUsage() { ); } + +export function FourColumns() { + return ( + + + First quarter + + + Second quarter + + + Third quarter + + + Fourth quarter + + + ); +} + +export function PageHeader() { + return ( + + Edit, + , + ]} + /> + + Order line items + + + Shipping details + + + ); +} + +export function HeaderWithChildren() { + return ( + + Edit]}> + + Supplier · Due 30 Nov 2026 + + + + Order line items + + + ); +} + +export function AreaMode() { + return ( + + + Sidebar + + + Content + + + ); +} + +export function GapSpacing() { + return ( + + + Main content + + + Sidebar + + + ); +} + +export function CustomLayout() { + return ( + + + A muted layout surface + + + ); +} + +export function ColumnStyling() { + return ( + + + Main content with a background and shadow + + + Sidebar overview + Additional information + + + ); +} diff --git a/docs-src/components/layout.docs.outline.md b/docs-src/components/layout.docs.outline.md index f3fecfd99..258b90c93 100644 --- a/docs-src/components/layout.docs.outline.md +++ b/docs-src/components/layout.docs.outline.md @@ -17,6 +17,8 @@ sources: import { Layout } from "@tailor-platform/app-shell"; ``` +The examples below also import `Button` and `Text` from `@tailor-platform/app-shell`. + ## Basic Usage The column count is auto-detected from the number of `Layout.Column` children: @@ -140,14 +142,7 @@ Left sidebar, main content, right sidebar: When more than 3 `Layout.Column` children are provided, all columns share equal width: -```tsx - - {/* 25% */} - {/* 25% */} - {/* 25% */} - {/* 25% */} - -``` + **Responsive behavior:** @@ -158,21 +153,7 @@ When more than 3 `Layout.Column` children are provided, all columns share equal Use `Layout.Header` to add a page-level header with title, actions, and optional full-width content: -```tsx - - Edit, - , - ]} - /> - {/* ... */} - {/* ... */} - -``` + The header displays: @@ -184,16 +165,7 @@ The header displays: Children render full-width below the title and actions row, such as a line of context about the record: -```tsx - - Edit]}> - - Acme Metals · Due 30 Nov 2026 - - - … - -``` + ## Area Mode @@ -208,16 +180,7 @@ By default, column widths are determined by position (first, second, third). You If any `Layout.Column` has an `area` prop, all columns switch to area-based widths. Columns without an `area` default to flexible (`1fr`). -```tsx - - - - - - Content - - -``` + Columns are rendered in source order — place them in the visual order you want. @@ -259,12 +222,7 @@ Use `fill` for pages whose main content manages its own scrolling (typically a ` Use the `gap` prop to control the space between columns. Supported steps are `4`, `6` and `8`: -```tsx - - {/* ... */} - {/* ... */} - -``` + ## Examples @@ -480,18 +438,11 @@ The Layout component validates its children: Add custom classes to the layout container. Keep to properties the layout doesn't set itself — it manages its own vertical padding and column gap (`gap`): -```tsx -{/* ... */} -``` + Add custom classes to individual columns: -```tsx - - {/* Main content with background */} - {/* Sidebar with extra spacing */} - -``` + ## Best Practices diff --git a/docs-src/components/menu.docs.examples.tsx b/docs-src/components/menu.docs.examples.tsx index b097e0b4d..3b506678e 100644 --- a/docs-src/components/menu.docs.examples.tsx +++ b/docs-src/components/menu.docs.examples.tsx @@ -1,4 +1,96 @@ -import { Menu } from "@tailor-platform/app-shell"; +import { useState } from "react"; +import { Button, Menu, Text } from "@tailor-platform/app-shell"; +import { EllipsisVerticalIcon } from "lucide-react"; + +export function CheckboxItems() { + const [bold, setBold] = useState(false); + const [italic, setItalic] = useState(false); + + return ( +
+ + }>Format text + + + ✓ + Bold + + + ✓ + Italic + + + + + Format this sample text. + + + Bold: {bold ? "on" : "off"}; italic: {italic ? "on" : "off"} + +
+ ); +} + +export function RadioItems() { + const [align, setAlign] = useState("left"); + + return ( +
+ + }>Align text + + + {["left", "center", "right"].map((value) => ( + + ● + {value} + + ))} + + + + + Align this sample text. + + Alignment: {align} +
+ ); +} + +export function RowActions() { + const orderNumber = "ORD-1001"; + const [lastAction, setLastAction] = useState("None"); + + return ( +
+
+ {orderNumber} + + }> + + + + setLastAction(`Edit ${orderNumber}`)}>Edit + setLastAction(`Duplicate ${orderNumber}`)}> + Duplicate + + + setLastAction(`View history for ${orderNumber}`)}> + View history + + + +
+ Last action: {lastAction} +
+ ); +} export function BasicUsage() { return ( @@ -13,3 +105,44 @@ export function BasicUsage() { ); } + +export function GroupedItems() { + return ( + + Actions + + + File + New + Open + + + + Edit + Cut + Copy + Paste + + + + ); +} + +export function NestedSubmenus() { + return ( + + Edit + + Cut + Copy + + Paste Special › + + Paste as Plain Text + Paste and Match Style + + + + + ); +} diff --git a/docs-src/components/menu.docs.outline.md b/docs-src/components/menu.docs.outline.md index ff88f7bff..d9eb3e307 100644 --- a/docs-src/components/menu.docs.outline.md +++ b/docs-src/components/menu.docs.outline.md @@ -17,6 +17,8 @@ The `Menu` component provides a dropdown menu with a compound component API. It import { Menu } from "@tailor-platform/app-shell"; ``` +The runnable examples also import `useState` from `react`, `Button` and `Text` from `@tailor-platform/app-shell`, and `EllipsisVerticalIcon` from `lucide-react`. + ## Basic Usage @@ -80,115 +82,31 @@ Accepts `className`, `disabled`, and all standard Base UI `Menu.Item` props. Use `Menu.Group` and `Menu.GroupLabel` to visually group related items: -```tsx - - Actions - - - File - New - Open - - - - Edit - Cut - Copy - Paste - - - -``` + ## Checkbox Items -```tsx -const [bold, setBold] = useState(false); -const [italic, setItalic] = useState(false); - - - Format - - - ✓ - Bold - - - ✓ - Italic - - -; -``` +Open **Format text** and toggle Bold or Italic. The sample text and the reported settings update together. + + ## Radio Items -```tsx -const [align, setAlign] = useState("left"); - - - Align - - - - ● - Left - - - ● - Center - - - ● - Right - - - -; -``` +Choose an alignment from **Align text**. Only one radio item is selected, and the sample text moves to that alignment. + + ## Nested Sub-menus -```tsx - - Edit - - Cut - Copy - - Paste Special › - - Paste as Plain Text - Paste and Match Style - - - - -``` + ## Examples -### Context Menu +### Row Actions Menu -```tsx -function OrderActions({ order }: { order: Order }) { - return ( - - - - - - handleEdit(order)}>Edit - handleDuplicate(order)}>Duplicate - - handleDelete(order)}>Delete - - - ); -} -``` +Open the order's three-dot button and choose an action. This is a button-triggered dropdown, not a right-click context menu. The example records the chosen action locally without modifying an order or navigating away. Use `render` to make the styled `Button` the trigger itself, rather than nesting two buttons. + + ## Accessibility diff --git a/docs-src/components/metric-card.docs.examples.tsx b/docs-src/components/metric-card.docs.examples.tsx index 7e7bee6ef..cd6f5d567 100644 --- a/docs-src/components/metric-card.docs.examples.tsx +++ b/docs-src/components/metric-card.docs.examples.tsx @@ -1,4 +1,5 @@ -import { MetricCard } from "@tailor-platform/app-shell"; +import { ShoppingCart } from "lucide-react"; +import { Grid, MetricCard } from "@tailor-platform/app-shell"; export function BasicUsage() { return ( @@ -10,3 +11,34 @@ export function BasicUsage() { /> ); } + +export function TrendDirections() { + return ( + + + + + + ); +} + +export function WithIcon() { + return ( + } + description="this week" + /> + ); +} diff --git a/docs-src/components/metric-card.docs.outline.md b/docs-src/components/metric-card.docs.outline.md index be2a7d1db..4f9e507ac 100644 --- a/docs-src/components/metric-card.docs.outline.md +++ b/docs-src/components/metric-card.docs.outline.md @@ -17,6 +17,8 @@ sources: import { MetricCard } from "@tailor-platform/app-shell"; ``` +The examples below also import `Grid` from `@tailor-platform/app-shell` and `ShoppingCart` from `lucide-react`. + ## Basic Usage @@ -29,33 +31,11 @@ import { MetricCard } from "@tailor-platform/app-shell"; - **down** — Negative change (destructive styling, e.g. red). - **neutral** — No change or neutral (muted styling). -```tsx - - - - - -``` + ## With Icon -```tsx -} description="this week" /> -``` + ## Related diff --git a/docs-src/components/select.docs.examples.tsx b/docs-src/components/select.docs.examples.tsx index 19fef7f48..6d64013eb 100644 --- a/docs-src/components/select.docs.examples.tsx +++ b/docs-src/components/select.docs.examples.tsx @@ -1,4 +1,5 @@ -import { Select } from "@tailor-platform/app-shell"; +import { useState } from "react"; +import { Field, Select, Text, type SelectAsyncFetcher } from "@tailor-platform/app-shell"; export function BasicUsage() { return ( @@ -9,3 +10,81 @@ export function BasicUsage() { /> ); } + +export function GroupedItems() { + const fruits = [ + { label: "Citrus", items: ["Orange", "Lemon", "Lime"] }, + { label: "Berries", items: ["Strawberry", "Blueberry"] }, + ]; + + return ({ label: fruit.name, key: String(fruit.id) })} + aria-label="Fruit" + placeholder="Pick a fruit" + onValueChange={(fruit) => console.log(fruit?.id)} + /> + ); +} + +export function MultiSelect() { + return ( + +
+ ); +} diff --git a/docs-src/components/select.docs.outline.md b/docs-src/components/select.docs.outline.md index 3a9a251d9..8c13b6abc 100644 --- a/docs-src/components/select.docs.outline.md +++ b/docs-src/components/select.docs.outline.md @@ -17,6 +17,8 @@ The `Select` component provides a fully assembled single or multi-select dropdow import { Select } from "@tailor-platform/app-shell"; ``` +The examples below also import `useState` from `react`, and `Field`, `Text`, and the `SelectAsyncFetcher` type from `@tailor-platform/app-shell`. + ## Basic Usage @@ -64,64 +66,25 @@ interface ItemGroup { ## Grouped Items -```tsx -const fruits = [ - { label: "Citrus", items: ["Orange", "Lemon", "Lime"] }, - { label: "Berries", items: ["Strawberry", "Blueberry"] }, -]; - - ({ label: fruit.name, key: String(fruit.id) })} - onValueChange={(fruit) => console.log(fruit?.id)} -/>; -``` + ## Multi-select -```tsx - -
-``` + Inside a `Field.Root`, the field's `name` identifies the value and these props are unnecessary — see [Form](./form.md). They matter for **native** submission: a plain `
`, `new FormData(form)`, diff --git a/docs-src/components/sheet.docs.examples.tsx b/docs-src/components/sheet.docs.examples.tsx index 8324a129c..a98333f0c 100644 --- a/docs-src/components/sheet.docs.examples.tsx +++ b/docs-src/components/sheet.docs.examples.tsx @@ -1,4 +1,4 @@ -import { Button, Sheet } from "@tailor-platform/app-shell"; +import { Button, Input, Sheet, Text } from "@tailor-platform/app-shell"; export function BasicUsage() { return ( @@ -16,3 +16,117 @@ export function BasicUsage() { ); } + +export function Sizes() { + const sizes = [ + { size: "sm", label: "Small", width: "384px (24rem) — default" }, + { size: "md", label: "Medium", width: "512px (32rem)" }, + { size: "lg", label: "Large", width: "720px (45rem)" }, + { size: "xl", label: "XL", width: "960px (60rem)" }, + { size: "full", label: "Full", width: "100% width" }, + ] as const; + return ( +
+ {sizes.map(({ size, label, width }) => ( + + }>Open {label} + + + {label} sheet + {width} + + Resize the viewport to see the panel's maximum width. + + + ))} +
+ ); +} + +export function Sides() { + return ( +
+ {(["right", "left", "top", "bottom"] as const).map((side) => ( + + }>Open {side} + + + Sheet from the {side} + + Swipe toward the {side} edge to dismiss. + + + ))} +
+ ); +} + +export function NonModal() { + return ( + + }>Open Inspector + + + Inspector + + The page remains interactive without a backdrop. + + + ); +} + +export function HeaderWithActions() { + return ( + + }>Edit Record + + }>Done}> + Edit Customer + +
+ +
+
+
+ ); +} + +export function FilterPanel() { + return ( + + }>Filters + + + Filter Orders + Narrow down orders by criteria. + +
+ + +
+ + }>Close + }>Apply Filters + +
+
+ ); +} + +export function BottomSheet() { + return ( + + }>More Options + + + Actions + +
+ }>Edit + }>Duplicate + }>Delete +
+
+
+ ); +} diff --git a/docs-src/components/sheet.docs.outline.md b/docs-src/components/sheet.docs.outline.md index 1f94456ad..55ef9ac3a 100644 --- a/docs-src/components/sheet.docs.outline.md +++ b/docs-src/components/sheet.docs.outline.md @@ -17,6 +17,8 @@ The `Sheet` component is a slide-in panel that appears from any edge of the scre import { Sheet } from "@tailor-platform/app-shell"; ``` +The examples below also import `Button`, `Input`, and `Text` from `@tailor-platform/app-shell`. + ## Basic Usage @@ -74,41 +76,11 @@ Accept a `render` prop for custom element rendering (Base UI render pattern), pl Control the width of the sheet panel using the `size` prop on `Sheet.Content`. This applies to `left` and `right` side sheets. -```tsx - - }>Open Small - … {/* 384px (24rem) — default */} - - - - }>Open Medium - … {/* 512px (32rem) */} - - - - }>Open Large - … {/* 720px (45rem) */} - - - - }>Open XL - … {/* 960px (60rem) */} - - - - }>Open Full - … {/* 100% width */} - -``` + ## Sides -```tsx -… {/* default — slides from right */} -… {/* slides from left */} -… {/* slides from top */} -… {/* slides from bottom */} -``` + The swipe-to-dismiss gesture direction is automatically determined by the `side` prop. @@ -132,16 +104,7 @@ const [open, setOpen] = useState(false); ## Non-modal Sheet -```tsx - - }>Open Inspector - - - Inspector - - - -``` + ## Examples @@ -149,63 +112,15 @@ const [open, setOpen] = useState(false); Place action buttons (e.g., save, edit) to the right of the title using the `action` prop on `Sheet.Header`. -```tsx - - }>Edit Record - - Save}> - Edit Customer - -
- -
-
-
-``` + ### Filter Panel -```tsx -function FilterPanel() { - return ( - - }>Filters - - - Filter Orders - Narrow down orders by criteria. - -
- - -
- - }>Clear - - -
-
- ); -} -``` + ### Bottom Sheet on Mobile -```tsx - - }>More Options - - - Actions - -
- - - -
-
-
-``` + ## Stacking diff --git a/docs-src/components/spinner.docs.examples.tsx b/docs-src/components/spinner.docs.examples.tsx index 067ae1f90..c2919d8d4 100644 --- a/docs-src/components/spinner.docs.examples.tsx +++ b/docs-src/components/spinner.docs.examples.tsx @@ -1,5 +1,28 @@ -import { Spinner } from "@tailor-platform/app-shell"; +import { Button, Spinner } from "@tailor-platform/app-shell"; export function BasicUsage() { return ; } + +export function AccessibleLoading() { + return ; +} + +export function DecorativeLoading() { + return ( + + ); +} + +export function SizingAndStyling() { + return ( +
+ + + +
+ ); +} diff --git a/docs-src/components/spinner.docs.outline.md b/docs-src/components/spinner.docs.outline.md index bffb10715..2451aee74 100644 --- a/docs-src/components/spinner.docs.outline.md +++ b/docs-src/components/spinner.docs.outline.md @@ -17,6 +17,8 @@ sources: import { Spinner } from "@tailor-platform/app-shell"; ``` +The examples below also import `Button` from `@tailor-platform/app-shell`. + ## Basic usage @@ -48,28 +50,17 @@ Preset sizes map to: Use a label when the spinner is the primary visible loading affordance: -```tsx - -``` + When the surrounding control already has its own accessible name, keep the spinner decorative: -```tsx - -``` + ## Sizing and styling Pass ordinary Tailwind utilities through `className` for color and layout, or override the dimensions directly with `width` / `height`. -```tsx - - - -``` + ## Related diff --git a/docs-src/components/table.docs.examples.tsx b/docs-src/components/table.docs.examples.tsx index cc06dea8b..e0d51307c 100644 --- a/docs-src/components/table.docs.examples.tsx +++ b/docs-src/components/table.docs.examples.tsx @@ -20,3 +20,93 @@ export function BasicUsage() { ); } + +export function WithFooter() { + return ( + + + + Product + Qty + Price + + + + + Widget A + 10 + $100.00 + + + Widget B + 5 + $75.00 + + + + + Total + $175.00 + + + + ); +} + +export function WithCaption() { + return ( + + Order line items + + + Item + Status + + + + + Item 1 + Shipped + + + + ); +} + +export function NumericAlignment() { + return ( + + + + Item + Amount + + + + + Widget A + 123 + + + + ); +} + +export function CenteredStatus() { + return ( + + + + Item + Status + + + + + Widget A + Active + + + + ); +} diff --git a/docs-src/components/table.docs.outline.md b/docs-src/components/table.docs.outline.md index 93340b34e..96c2a8f06 100644 --- a/docs-src/components/table.docs.outline.md +++ b/docs-src/components/table.docs.outline.md @@ -54,93 +54,19 @@ All other sub-components (`Table.Header`, `Table.Body`, `Table.Footer`, `Table.R ### With Footer -```tsx - - - - Product - Qty - Price - - - - - Widget A - 10 - $100.00 - - - Widget B - 5 - $75.00 - - - - - Total - $175.00 - - - -``` + ### With Caption -```tsx - - Order line items - - - Item - Status - - - - - Item 1 - Shipped - - - -``` + ### Right-aligned numeric columns -```tsx - - - - Item - Amount - - - - - Widget A - 123 - - - -``` + ### Center-aligned status column -```tsx - - - - Item - Status - - - - - Widget A - Active - - - -``` + ### Constrained Height with Scroll diff --git a/docs-src/components/tabs.docs.examples.tsx b/docs-src/components/tabs.docs.examples.tsx index 89452421b..c8c771cc6 100644 --- a/docs-src/components/tabs.docs.examples.tsx +++ b/docs-src/components/tabs.docs.examples.tsx @@ -1,4 +1,5 @@ import { Tabs } from "@tailor-platform/app-shell"; +import { FolderKanbanIcon, LayoutDashboardIcon, SettingsIcon } from "lucide-react"; export function BasicUsage() { return ( @@ -14,3 +15,41 @@ export function BasicUsage() { ); } + +export function DisabledTab() { + return ( + + + Active + Pending + + Archived + + + Active items + Pending items + Archived items + + ); +} + +export function IconTabs() { + return ( + + + + + + + + + + + + + Overview content + Projects content + Settings content + + ); +} diff --git a/docs-src/components/tabs.docs.outline.md b/docs-src/components/tabs.docs.outline.md index e8c20fecf..63500b168 100644 --- a/docs-src/components/tabs.docs.outline.md +++ b/docs-src/components/tabs.docs.outline.md @@ -17,6 +17,8 @@ The `Tabs` component provides tab-based navigation for toggling between related import { Tabs } from "@tailor-platform/app-shell"; ``` +The examples below also import `FolderKanbanIcon`, `LayoutDashboardIcon`, and `SettingsIcon` from `lucide-react`. + ## Basic Usage @@ -115,20 +117,7 @@ another control, such as a `Select`, over relying on the scroll. ### With Disabled Tab -```tsx - - - Active - Pending - - Archived - - - Active items - Pending items - Archived items - -``` + ### Use Icons in Tab @@ -141,24 +130,7 @@ icons default to `16px`, so the square is consistent regardless of the icon. > **Accessibility:** an icon-only tab has no visible text, so give each one an > `aria-label`. Without it, screen readers announce an unnamed tab. -```tsx - - - - - - - - - - - - - Overview content - Projects content - Settings content - -``` + ### Sizing the capsule variant diff --git a/docs-src/components/text.docs.examples.tsx b/docs-src/components/text.docs.examples.tsx index ed8cd8956..e7a36f66e 100644 --- a/docs-src/components/text.docs.examples.tsx +++ b/docs-src/components/text.docs.examples.tsx @@ -1,4 +1,5 @@ -import { Text } from "@tailor-platform/app-shell"; +import { useId } from "react"; +import { Input, Table, Text } from "@tailor-platform/app-shell"; export function BasicUsage() { return ( @@ -41,9 +42,61 @@ export function ColorAndModifiers() { Orders sent this month. + + Card title + 1,240.00
); } + +export function ElementRoles() { + return ( +
+ A compact page title + A visually prominent subsection + Updated recently +
+ ); +} + +export function RenderLabel() { + const id = useId(); + return ( +
+ }> + Quantity + + +
+ ); +} + +export function HeadingLevel() { + return Line items; +} + +export function NonHeadingRole() { + return 1,240 orders; +} + +export function RolesWithoutText() { + return ( + + + + + Amount + + + + + + $1,240.00 + + + + ); +} diff --git a/docs-src/components/text.docs.outline.md b/docs-src/components/text.docs.outline.md index 70063bbdb..60f5cc8b3 100644 --- a/docs-src/components/text.docs.outline.md +++ b/docs-src/components/text.docs.outline.md @@ -17,6 +17,8 @@ The `Text` component applies a [typography role](../concepts/styling-theming.md# import { Text } from "@tailor-platform/app-shell"; ``` +The examples below also import `Input` and `Table` from `@tailor-platform/app-shell` and `useId` from `react`. + ## Basic Usage @@ -40,11 +42,7 @@ import { Text } from "@tailor-platform/app-shell"; The element sets the meaning and `variant` sets the appearance. The default is only a starting point, and any role works on any element: -```tsx -A compact page title -A visually prominent subsection -Updated recently -``` + The element components take `variant`, `className`, the element's own attributes, and a ref typed for the element (`HTMLHeadingElement` for `Text.h2`). They do not take `render`. For any other element, or to compose with another component, use `Text` with `render`. @@ -52,11 +50,7 @@ The element components take `variant`, `className`, the element's own attributes All standard HTML attributes are also accepted by `Text`. Put an attribute that belongs to one element, such as `htmlFor` on a `label`, on the `render` element: -```tsx -}> - Quantity - -``` + Some lint rules report this example; see [Lint](#lint). @@ -85,15 +79,11 @@ The sizes and line heights are in the [Typography section of the styling guide]( On `Text`, all three heading roles render `h2` by default. The heading level comes from the document structure, not from the visual size, so set it with `Text.h1` to `Text.h6`: -```tsx -Line items -``` + To use a heading role for text that is not a heading, use `Text.div` or `Text.span`: -```tsx -1,240 orders -``` + ## Lint @@ -114,27 +104,13 @@ Set the color with a color token in `className`. Four modifiers may also be comb -```tsx - - Orders sent this month. - - - Card title - - - 1,240.00 - -``` - Do not combine a role with other `leading-*`, `tracking-*`, or `text-*` size values. Pick a different `variant` instead. A `text-*` size class such as `text-sm` has no effect on `Text`: AppShell's stylesheet loads after yours, so the role's size wins. ## Using Roles Without Text Each role is also a plain utility, for example `text-heading-md`. Use the utility when you style your own element and do not need `Text`: -```tsx -Amount -``` + ## TypeScript diff --git a/docs-src/components/textarea.docs.examples.tsx b/docs-src/components/textarea.docs.examples.tsx index 1da760861..6ffb10065 100644 --- a/docs-src/components/textarea.docs.examples.tsx +++ b/docs-src/components/textarea.docs.examples.tsx @@ -1,5 +1,23 @@ -import { Textarea } from "@tailor-platform/app-shell"; +import { Field, Textarea } from "@tailor-platform/app-shell"; export function BasicUsage() { return