@flipdish/ui-library 0.2.1 → 0.2.2

package/README.md

@@ -1,119 +1,56 @@
 # `@flipdish/ui-library`
 
-Atomic-design component library for the property-service MFE. Built on Tailwind v4 + Untitled UI primitives, consumed by `packages/frontend`.
-
----
-
-## TODO: future extraction to a standalone repo
-
-This package already uses its final name, `@flipdish/ui-library`. Inside this monorepo it resolves to source via `workspace:*` (no build step); the import paths below are the public API today and stay identical after extraction.
-
-**Why call out a future extraction:**
-
-- This package is currently one MFE's POC; the published library will be a curated, org-wide system maintained by the design-system team.
-- Keeping the name and import surface stable now means the move to a standalone repo + published npm package is a mechanical change, not an API break.
-
-**When to extract:**
-
-When the design system team is ready to move this library to its own repo and publish to internal npm. At that point:
-
-1. Move source out to a new `flipdish/ui-library` (or equivalent) repo.
-2. Keep `name` in `package.json` as `@flipdish/ui-library` (already set).
-3. Add a build pipeline (Vite/Rollup → `dist/`). Then expand each entry in `exports` from the source-only shorthand:
-   ```jsonc
-   "./atoms/*": "./src/components/atoms/*/index.tsx"
-   ```
-   to the conditional shape used by `@flipdish/portal-library`:
-   ```jsonc
-   "./atoms/*": {
-     "types": "./dist/components/atoms/*/index.d.ts",
-     "import": "./dist/components/atoms/*/index.js",
-     "node":   "./dist/components/atoms/*/index.cjs.js"
-   }
-   ```
-   The keys (`./atoms/*` etc.) stay identical, so consumer import paths don't change.
-4. Add `tailwindcss`, `@tailwindcss/vite`, `postcss-prefix-selector`, `vite-plugin-css-injected-by-js` to the new repo's `devDependencies` (needed at that point for Storybook + the lib's own build).
-5. In the consuming repo, replace `"@flipdish/ui-library": "workspace:*"` with `"@flipdish/ui-library": "^<version>"`.
-6. Import sites need no changes — the package name and subpaths are unchanged.
-7. Delete `packages/ui-library/` from this repo.
-8. Renovate (already wired in `renovate.json`) auto-updates minor/patch versions thereafter.
-
-The rename is a single mechanical PR — the API shape (`peerDependencies`, exports keys, atomic folder structure) stays the same. Naming today is therefore a _placeholder_, not a contract.
-
-The same pattern applies to the planned design-tokens package: scaffolded as `@flipdish/ui-tokens` locally, will extract to `@flipdish/ui-tokens` later.
-
----
-
-## Layout
-
-```text
-src/
-├── styles.css                                     # shared Tailwind runtime (plugins, variants, @utility, base resets) → `@flipdish/ui-library/styles`
-├── components/
-│   ├── atoms/                                     # paste target — smallest building blocks (Button, Input, Badge …)
-│   ├── molecules/                                 # paste target — compose atoms (FormField, RadioGroup …)
-│   ├── organisms/                                 # paste target — compose atoms + molecules (Modal, Toaster …)
-│   └── templates/                                 # page-shaped layouts (NotFoundPage, PageLayout, MfeShell)
-│       └── NotFoundPage/
-│           ├── index.tsx                          # component implementation (not a barrel)
-│           └── NotFoundPage.test.tsx              # co-located test (greppable name)
-├── providers/                                     # cross-cutting behavioural wrappers, NOT on the visual atomic ladder (ErrorBoundary …)
-│   └── ErrorBoundary/                             # wraps react-error-boundary behind a stable seam → `@flipdish/ui-library/providers/ErrorBoundary`
-│       └── index.tsx
-├── hooks/                                         # layer-agnostic hooks (useMediaQuery …) — paste target
-├── utilities/                                     # layer-agnostic helpers
-│   ├── cx/
-│   │   └── index.ts                               # cx (extendTailwindMerge wrapper) + sortCx — shared, pure JS
-│   └── renderUtils/
-│       ├── index.ts                               # getMicroFrontendAttribute, lazyWithRetry, getAppId, ... (web-only MFE runtime)
-│       └── renderUtils.test.ts                    # co-located test (planned)
-```
+Atomic-design React component library for Flipdish products, built on **Tailwind CSS v4**, [Untitled UI](https://www.untitledui.com/) primitives, and [React Aria Components](https://react-spectrum.adobe.com/react-aria/). Web-first today, with React Native (via [NativeWind](https://www.nativewind.dev/)) support rolling out per component.
 
-Empty atomic layers carry a `.gitkeep` until the first component is pasted. The
-class-merge helper is `cx`/`sortCx` (Untitled UI naming), living under
-`utilities/` — there is no separate `utils/cn`.
+> **Internal design system, published publicly.** This package is built for and tuned to Flipdish's brand and tooling. It's on the public npm registry so it can be shared across Flipdish micro-frontends and apps — it isn't intended as a general-purpose UI kit.
 
-**Single convention across the lib — folder-as-module everywhere:**
+**Part of the Flipdish Design System:**
 
-- Every module lives in its own folder named after the export (`Button/`, `NotFoundPage/`, `renderUtils/`, `cx/`).
-- The folder contains `index.ts` (or `index.tsx` for components) — this is the **implementation**, not a barrel re-export.
-- Co-located files use the explicit name to stay greppable: `Button/Button.test.tsx`, `renderUtils/renderUtils.test.ts`, `Button/Button.variants.ts`.
-- No barrel files anywhere — every export comes from the folder's own `index.ts`.
+| Package                                                                    | Purpose                                      |
+| -------------------------------------------------------------------------- | -------------------------------------------- |
+| [`@flipdish/ui-tokens`](https://www.npmjs.com/package/@flipdish/ui-tokens) | Design tokens — colours, type scale, spacing |
+| [`@flipdish/ui-icons`](https://www.npmjs.com/package/@flipdish/ui-icons)   | Icon set                                     |
+| **`@flipdish/ui-library`**                                                 | Components (this package)                    |
 
-Why one convention instead of two? The lib's import paths are its public API; a single folder-as-module pattern produces consistently short, predictable paths (`@flipdish/ui-library/utilities/renderUtils`) and matches how the components are organised. The `packages/frontend/.cursor/rules/flipdish/ui-folder-structure.mdc` rule that uses `<name>/<name>.utils.ts` is scoped to `packages/frontend/**` only — frontend feature code follows it, ui-library doesn't.
+## Installation
 
-**Public consumption** is via wildcard entries in the `exports` field — one per atomic layer (under `components/`) plus `providers`, `hooks` and `utilities`. Component import paths mirror the on-disk folder structure (`components/<layer>/<Name>`). Every wildcard resolves to `<name>/index.{ts,tsx}`:
+```bash
+pnpm add @flipdish/ui-library
+```
 
-```ts
-// Components
-import { Button } from "@flipdish/ui-library/components/atoms/Button";
-import { NotFoundPage } from "@flipdish/ui-library/components/templates/NotFoundPage";
+### Peer dependencies
 
-// Providers — cross-cutting behavioural wrappers
-import { ErrorBoundary } from "@flipdish/ui-library/providers/ErrorBoundary";
+Install the peers for the platform(s) you target. Platform-specific peers are declared `optional`, so a web-only consumer is never warned about the React Native stack (and vice versa).
 
-// Hooks
-import { useMediaQuery } from "@flipdish/ui-library/hooks/useMediaQuery";
+**Shared — required on every platform:**
 
-// Utilities — class-merge helper + MFE runtime helpers
-import { cx, sortCx } from "@flipdish/ui-library/utilities/cx";
-import {
-  getMicroFrontendAttribute,
-  lazyWithRetry,
-} from "@flipdish/ui-library/utilities/renderUtils";
-```
+| Package             | Version   |
+| ------------------- | --------- |
+| `react`             | `^19.0.0` |
+| `clsx`              | `^2.1.1`  |
+| `tailwind-merge`    | `^3.6.0`  |
+| `tailwind-variants` | `^3.2.2`  |
+
+**Web:**
+
+| Package                 | Version   |
+| ----------------------- | --------- |
+| `react-dom`             | `^19.0.0` |
+| `react-aria-components` | `^1.18.0` |
+| `react-router`          | `^7.0.0`  |
 
-Adding a new module (anywhere) is **zero `package.json` changes** — create `src/<area>/<name>/index.ts` and it's importable as `@flipdish/ui-library/<area>/<name>` (e.g. `src/components/atoms/Button/index.tsx` → `@flipdish/ui-library/components/atoms/Button`).
+**React Native:**
 
-The wildcards point straight at `.tsx`/`.ts` source (no build step); the consumer's bundler compiles ui-library as part of its own pipeline.
+| Package                           | Version    |
+| --------------------------------- | ---------- |
+| `react-native`                    | `>=0.79.0` |
+| `nativewind`                      | `^4.1.0`   |
+| `@react-native-aria/interactions` | `>=0.2.7`  |
+| `@react-native-aria/focus`        | `>=0.2.7`  |
 
-## Shared Tailwind runtime (`./styles`)
+## Tailwind setup
 
-Everything pasted Untitled UI components depend on at the CSS level — the Tailwind
-plugins, custom variants, `@utility` definitions, base resets — plus the `@source`
-that scans this library for class names, is centralised in `src/styles.css` and
-exported as `@flipdish/ui-library/styles`. Consumers import it from their
-Tailwind entry CSS so each MFE/app doesn't re-declare it:
+The library ships a shared Tailwind runtime — plugins, custom variants, `@utility` definitions, and base resets — at `@flipdish/ui-library/styles`. Import it from your Tailwind entry CSS, alongside the tokens, so each app doesn't re-declare it:
 
 ```css
 @layer theme, base, components, utilities;
@@ -121,218 +58,50 @@ Tailwind entry CSS so each MFE/app doesn't re-declare it:
 @import "tailwindcss/theme.css" layer(theme);
 @import "@flipdish/ui-tokens/css" layer(theme); /* tokens + [data-theme="dark"] */
 @import "tailwindcss/preflight.css" layer(base);
-@import "@flipdish/ui-library/styles"; /* plugins, variants, @utility, resets, @source */
+@import "@flipdish/ui-library/styles"; /* plugins, variants, @utility, resets */
 @import "tailwindcss/utilities.css" layer(utilities);
 ```
 
-What stays in the **consumer's** entry CSS (app/bundler concerns, not library
-concerns): the `@layer` order, the `tailwindcss` theme/preflight/utilities imports,
-and any PostCSS scoping (e.g. property-service's `#flipdish-micro-frontend` prefix
-pipeline). `styles.css` declares `@plugin`s, so the plugin packages are ui-library
-`dependencies` (see below) — `@plugin` resolves relative to the file declaring it.
-
-## Design tokens
-
-Tokens (brand colors, type scale, spacing overrides) do **not** live in this package — they live in the separate `@flipdish/ui-tokens` workspace package (also planned for future extraction to `@flipdish/ui-tokens`). See Phase 2.5 of the migration plan.
-
-## Dependency conventions
-
-Mirrors the `@flipdish/portal-library` shape so the eventual extraction is a clean rename, not a dep-graph restructure.
-
-### Runtime deps → `peerDependencies` (with matching `devDependencies` for typecheck)
-
-Peers are split into three buckets: **shared** (every consumer needs them, on any
-platform) and two **platform-specific** buckets (`web-only` / `app-only`) that are
-marked `optional` so a consumer is never warned about the other platform's stack.
-
-**Shared — required on every platform:**
-
-| Package             | Why peer                                                                               | Version   |
-| ------------------- | -------------------------------------------------------------------------------------- | --------- |
-| `react`             | Hooks need a singleton React; shared by web + RN                                       | `^19.0.0` |
-| `clsx`              | Consumer feature code imports it directly; available for conditional class composition | `^2.1.1`  |
-| `tailwind-merge`    | Used by the `cx()` helper; sharing one version avoids divergent Tailwind merge configs | `^3.6.0`  |
-| `tailwind-variants` | Variant/slot config for component class strings — identical strings resolve on both    | `^3.2.2`  |
-
-**Web-only — `optional` peers (a web consumer provides them; RN never does):**
-
-| Package                 | Why peer                                                                                                           | Version   |
-| ----------------------- | ------------------------------------------------------------------------------------------------------------------ | --------- |
-| `react-dom`             | Web React renderer; no RN equivalent                                                                               | `^19.0.0` |
-| `react-aria-components` | Web-only a11y primitives Untitled UI is built on (quarantined — see cross-platform rule)                           | `^1.18.0` |
-| `react-router`          | Web routing — `providers/RouteProvider` feeds it into RAC's `RouterProvider`; RN uses react-navigation, never this | `^7.0.0`  |
-
-**App-only (React Native) — `optional` peers (an RN consumer provides them; web never does):**
-
-| Package                           | Why peer                                                                 | Version    |
-| --------------------------------- | ------------------------------------------------------------------------ | ---------- |
-| `react-native`                    | RN primitives (`View`, `Pressable`, `TextInput`) used by `.native.tsx`   | `>=0.79.0` |
-| `nativewind`                      | Resolves the shared Tailwind class strings to RN styles at build time    | `^4.1.0`   |
-| `@react-native-aria/interactions` | RN a11y/interaction hooks — the `react-aria-components` equivalent on RN | `>=0.2.7`  |
-| `@react-native-aria/focus`        | RN focus management hooks (composed by `.native.tsx` overlay components) | `>=0.2.7`  |
+The library ships pre-built — compiled ESM and CommonJS with TypeScript declarations — so each subpath resolves to built output in `dist/`.
 
-> **Mirrored in `package.json`.** The same `shared` / `web` / `app` split is encoded
-> as the `x-peer-platforms` field (an `x-`-prefixed field npm/pnpm ignore at install
-> time, since `package.json` allows no comments — purely self-documenting). Nothing
-> enforces consistency, so when you add, rename, or move a peer, update **all three** in
-> lock-step: `peerDependencies`, `peerDependenciesMeta` (the `optional` flag for platform
-> peers), and `x-peer-platforms` — plus the table above.
+## Usage
 
-#### Why `optional` instead of required
+Components, providers, hooks, and utilities are imported from subpaths that mirror the atomic-design layers:
 
-All platform-specific peers are listed in `peerDependenciesMeta` as
-`{ "optional": true }`. `peerDependenciesMeta` is **global** (not per-platform), so
-optional is the only setting that lets a web consumer install without `react-native`
-**and** an RN consumer install without `react-aria-components` — neither gets a
-spurious "missing peer" warning, and **no consumer-side suppression** (`ignoreMissing`,
-`auto-install-peers=false`, `legacy-peer-deps`) is needed. The version ranges still
-apply when a peer **is** present, so a mismatched version is still flagged.
-
-**Trade-off (deliberate):** optional peers drop the install-time guarantee that a web
-consumer has `react-aria-components`. That enforcement instead happens where it's
-unambiguous about platform: the **bundler** (a web build importing a RAC-based
-component fails to resolve the missing module) and the **Cursor rules**
-(`cross-platform-components.mdc` quarantines RAC to web `index.tsx`). This keeps the
-single shared package honest for both platforms without forcing either consumer to
-carry the other's dependencies.
-
-#### `devDependencies` mirror (local typecheck only — never shipped)
-
-Each peer the source actually imports is mirrored in `devDependencies` so the lib's
-own typecheck resolves it:
-
-- **Web** (`pnpm typecheck`): `@types/react`, `@types/react-dom`, `react-aria-components`, `react-router`, `clsx`, `tailwind-merge`, `tailwind-variants`.
-- **App** (`pnpm typecheck:native`): `react-native` + `nativewind` (RN module/`className` types). `@react-native-aria/*` are **not** dev-installed yet — they're added per-component when the first overlay `index.native.tsx` (Modal, Select, RadioGroup, …) is written; until then they exist only as optional peers for the RN consumer to provide.
-
-`@types/react-native` is intentionally **omitted** — it's deprecated and React Native
-ships its own types since 0.71; adding the DefinitelyTyped package causes duplicate
-global definitions.
-
-The class-merge helper is `cx` (`extendTailwindMerge` wrapper, per Untitled UI's Vite
-guide) — not a `cn`/`clsx` wrapper.
-
-#### Platform-split typecheck (`tsconfig.json` vs `tsconfig.native.json`)
-
-The two platforms have conflicting global types (web has the `DOM` lib; RN does not),
-so they typecheck under separate configs:
-
-- `tsconfig.json` → web. Has `lib: ["DOM", …]`; **excludes** `**/*.native.ts(x)` so RN
-  files (which import `react-native`) never get checked under the DOM lib.
-- `tsconfig.native.json` → app. Drops the `DOM` lib (`lib: ["ES2020"]`) so any
-  accidental `window`/`document`/DOM usage in RN-bound code is a compile error rather
-  than a runtime Metro-bundle break. RN module types resolve via normal imports, so no
-  `types` override is needed.
-
-Because the package currently ships web-only, `tsconfig.native.json` anchors its
-program on the shared, DOM-free utilities (`utilities/cx`, `utilities/isReactComponent`)
-so `typecheck:native` has inputs (no `TS18003`) before any `.native.tsx` exists. New
-`*.native.ts(x)` files are picked up automatically by its include globs.
-
-### Tailwind plugins declared by `styles.css` → ui-library `dependencies`
-
-| Package                             | Why                                                                |
-| ----------------------------------- | ------------------------------------------------------------------ |
-| `tailwindcss-animate`               | `@plugin` declared in `styles.css`; must resolve from this package |
-| `tailwindcss-react-aria-components` | `@plugin` declared in `styles.css`; powers RAC-aware variants      |
-
-Because `@flipdish/ui-library/styles` declares these via `@plugin`, and
-`@plugin` resolves relative to the file declaring it, the plugins are real
-`dependencies` of ui-library (installed transitively wherever ui-library is) — the
-consumer no longer lists them.
-
-### Encapsulated runtime libs → ui-library `dependencies`
-
-| Package                | Why                                                                                            |
-| ---------------------- | ---------------------------------------------------------------------------------------------- |
-| `react-error-boundary` | Wrapped behind `providers/ErrorBoundary`; consumers use that seam and never import it directly |
-
-Unlike the runtime **peers** above (which the consumer also imports), this is an
-implementation detail of `providers/ErrorBoundary`. It's a plain `dependency` so it
-resolves from this package and ships transitively — the consumer imports
-`@flipdish/ui-library/providers/ErrorBoundary`, not `react-error-boundary`.
-It's RN-safe, so it stays a regular dep rather than a web-only one.
+```ts
+// Components — components/<atoms|molecules|organisms|templates>/<Name>
+import { Button } from "@flipdish/ui-library/components/atoms/Button";
+import { NotFoundPage } from "@flipdish/ui-library/components/templates/NotFoundPage";
 
-### App build tools → NOT in ui-library deps
+// Providers — cross-cutting behavioural wrappers
+import { ThemeProvider } from "@flipdish/ui-library/providers/ThemeProvider";
+import { RouteProvider } from "@flipdish/ui-library/providers/RouteProvider";
+import { ErrorBoundary } from "@flipdish/ui-library/providers/ErrorBoundary";
 
-`tailwindcss`, `@tailwindcss/vite`, `postcss-prefix-selector`, `vite-plugin-css-injected-by-js` are **build tools for the consuming app**. ui-library never imports them in source — Tailwind classes are plain strings. They stay in `packages/frontend/devDependencies` only.
+// Hooks
+import { useBreakpoint } from "@flipdish/ui-library/hooks/useBreakpoints";
+import { useClipboard } from "@flipdish/ui-library/hooks/useClipboard";
 
-Add them to ui-library's `devDependencies` ONLY when this package gains its own build pipeline (Storybook, Vitest with real CSS rendering, standalone preview app, etc.). Until then, keeping ui-library minimal avoids dead-weight installs.
-
-### Atomic design dependency direction
+// Utilities
+import { cx, sortCx } from "@flipdish/ui-library/utilities/cx";
+```
 
-Import direction is enforced via the package Cursor rules + code review (this repo
-lints TS with Biome, which can't express wildcard atomic-layer import bans):
+### Styling rules
 
-- atoms → no internal deps
-- molecules → may import atoms
-- organisms → may import atoms + molecules
-- templates → may import atoms + molecules + organisms
+Use **semantic** token utilities only (`bg-primary`, `text-secondary`, `border-primary`, `bg-brand-solid`, …) — never primitive ramp utilities (`bg-blue-500`) or raw `var(--…)` in `style`. Semantic tokens swap automatically under `[data-theme="dark"]`; primitives don't.
 
-Hooks and utilities are layer-agnostic and may be imported anywhere (but must not
-import components).
+## Platform support (web + React Native)
 
-## Pasting Untitled UI components
+The component API, `tailwind-variants` configs, and `cx`/`sortCx` are shared across platforms; primitives and accessibility libraries diverge via a `.tsx` (web) + `.native.tsx` (RN) file split.
 
-Untitled UI source uses a `@/` alias that does NOT resolve inside this package
-(the frontend already owns `@/`). When pasting a component, rewrite its imports to
-package paths and drop the file into the right atomic layer:
+`react-aria-components` (which Untitled UI is built on) is **web-only**, so a component is React Native-ready only once it ships an `index.native.tsx` sibling. The presence of that file is the source of truth — Metro resolves `index.native.tsx` automatically, while web bundlers use the `index.tsx`.
 
-| Untitled UI import                 | Rewrite to                                                      |
-| ---------------------------------- | --------------------------------------------------------------- |
-| `@/utils/cx`                       | `@flipdish/ui-library/utilities/cx`                             |
-| `@/components/base/buttons/button` | `@flipdish/ui-library/components/atoms/Button` (classify layer) |
-| `@/hooks/use-x`                    | `@flipdish/ui-library/hooks/useX`                               |
-| `@untitledui/icons`                | `@flipdish/ui-icons` (same named exports)                       |
+**Today the library is web-only** — no component ships a `.native.tsx` sibling yet. As React Native support lands per component, check the component's folder for an `index.native.tsx` ([browse the source](https://github.com/flipdishbytes/flipdish-design-system/tree/main/packages/ui-library/src/components)) rather than relying on a list here that would drift between releases.
 
-**Icons are out of scope for this library.** `@untitledui/icons` is intentionally
-NOT a dependency. Icons live in the separate `@flipdish/ui-icons` package,
-which re-exports `@untitledui/icons` behind a stable seam. When pasting a component
-that imports `@untitledui/icons`, rewrite the import to `@flipdish/ui-icons`
-(the named exports are identical) — never import `@untitledui/icons` directly here.
+## Changelog
 
-Use SEMANTIC token utilities only (`bg-primary`, `text-secondary`, …) — never raw
-ramp utilities (`bg-blue-500`). This package's `styles.css`
-(`@flipdish/ui-library/styles`) provides the Tailwind plugins, `dark`
-variant (mapped to `[data-theme="dark"]`), and `@utility` definitions
-(`transition-inherit-all`, `scrollbar-hide`) these components expect — the consumer
-just imports it. See `.cursor/rules/atomic-design.mdc`.
+See [CHANGELOG.md](https://github.com/flipdishbytes/flipdish-design-system/blob/main/packages/ui-library/CHANGELOG.md) for release history.
 
-## Platform support (web + React Native)
+## Contributing
 
-This library targets web AND React Native (via NativeWind). Tokens, the component
-API, `tailwind-variants` configs, and `cx`/`sortCx` are shared; primitives and a11y
-libraries diverge via a `.tsx` (web) + `.native.tsx` (RN) file split. See
-`.cursor/rules/cross-platform-components.mdc`.
-
-`react-aria-components` (which Untitled UI is built on) is **web-only**. A pasted
-component is web-only until an `index.native.tsx` sibling is written. Metro falls
-back to `index.tsx` when no native sibling exists, so RN consumers must only import
-components marked RN-ready below.
-
-| Component        | Layer    | RN status                                               |
-| ---------------- | -------- | ------------------------------------------------------- |
-| Avatar           | atom     | TODO(RN) (web markup; no `.native.tsx` yet)             |
-| Badge            | atom     | TODO(RN) (web markup; no `.native.tsx` yet)             |
-| Button           | atom     | TODO(RN) (RAC-based; web-only until `.native.tsx`)      |
-| Checkbox         | atom     | TODO(RN) (RAC-based; web-only until `.native.tsx`)      |
-| Divider          | atom     | TODO(RN) (web markup; no `.native.tsx` yet)             |
-| Dot              | atom     | TODO(RN) (web markup; no `.native.tsx` yet)             |
-| FeaturedIcon     | atom     | TODO(RN) (web markup; no `.native.tsx` yet)             |
-| Input            | atom     | TODO(RN) (RAC-based; web-only until `.native.tsx`)      |
-| LoadingIndicator | atom     | TODO(RN) (web markup; no `.native.tsx` yet)             |
-| RadioButton      | atom     | TODO(RN) (RAC-based; web-only until `.native.tsx`)      |
-| Toggle           | atom     | TODO(RN) (RAC-based; web-only until `.native.tsx`)      |
-| Tooltip          | atom     | TODO(RN) (RAC-based; web-only until `.native.tsx`)      |
-| Breadcrumbs      | molecule | TODO(RN) (RAC-based; web-only until `.native.tsx`)      |
-| ButtonGroup      | molecule | TODO(RN) (RAC-based; web-only until `.native.tsx`)      |
-| Dropdown         | molecule | TODO(RN) (RAC-based; web-only until `.native.tsx`)      |
-| RadioGroup       | molecule | TODO(RN) (RAC-based; web-only until `.native.tsx`)      |
-| SectionHeader    | molecule | TODO(RN) (web markup; no `.native.tsx` yet)             |
-| Select           | molecule | TODO(RN) (RAC-based; web-only until `.native.tsx`)      |
-| PageHeader       | organism | TODO(RN) (web markup; composes Button + Input)          |
-| NotFoundPage     | template | No (web-only template)                                  |
-| PageLayout       | template | No (web-only template; renders `<main>`)                |
-| ErrorBoundary    | provider | TODO(RN) (logic RN-safe; default fallback is a `<div>`) |
-
-_(Table grows as components are added. `Yes` = has `.native.tsx`; `No` = web-only by
-design; `TODO(RN)` = web ships, RN sibling pending.)_
+This package lives in the [`flipdish-design-system`](https://github.com/flipdishbytes/flipdish-design-system) monorepo. Contributor documentation — folder conventions, how Untitled UI components are adapted, the web/native file split, and dependency rules — lives alongside the source there.

package/dist/hooks/useBreakpoints/index.cjs

@@ -0,0 +1,39 @@
+'use strict';
+
+var React = require('react');
+
+const screens = {
+    sm: '640px',
+    md: '768px',
+    lg: '1024px',
+    xl: '1280px',
+    '2xl': '1536px',
+};
+/**
+ * Checks whether a particular Tailwind CSS viewport size applies.
+ *
+ * @param size The size to check, which must either be included in Tailwind CSS's
+ * list of default screen sizes, or added to the Tailwind CSS config file.
+ *
+ * @returns A boolean indicating whether the viewport size applies.
+ */
+const useBreakpoint = (size) => {
+    const query = `(min-width: ${screens[size]})`;
+    const getMatches = () => (typeof window !== 'undefined' && typeof window.matchMedia === 'function' ? window.matchMedia(query).matches : false);
+    const [matches, setMatches] = React.useState(getMatches);
+    React.useEffect(() => {
+        if (typeof window === 'undefined' || typeof window.matchMedia !== 'function') {
+            setMatches(false);
+            return;
+        }
+        const breakpoint = window.matchMedia(query);
+        setMatches(breakpoint.matches);
+        const handleChange = (value) => setMatches(value.matches);
+        breakpoint.addEventListener('change', handleChange);
+        return () => breakpoint.removeEventListener('change', handleChange);
+    }, [query]);
+    return matches;
+};
+
+exports.useBreakpoint = useBreakpoint;
+//# sourceMappingURL=index.cjs.map

package/dist/hooks/useBreakpoints/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.cjs","sources":["../../../src/hooks/useBreakpoints/index.ts"],"sourcesContent":[null],"names":["useState","useEffect"],"mappings":";;;;AAEA,MAAM,OAAO,GAAG;AACd,IAAA,EAAE,EAAE,OAAO;AACX,IAAA,EAAE,EAAE,OAAO;AACX,IAAA,EAAE,EAAE,QAAQ;AACZ,IAAA,EAAE,EAAE,QAAQ;AACZ,IAAA,KAAK,EAAE,QAAQ;CACP;AAIV;;;;;;;AAOG;AACI,MAAM,aAAa,GAAG,CAAC,IAAgB,KAAI;IAChD,MAAM,KAAK,GAAG,CAAA,YAAA,EAAe,OAAO,CAAC,IAAI,CAAC,GAAG;AAE7C,IAAA,MAAM,UAAU,GAAG,OAAO,OAAO,MAAM,KAAK,WAAW,IAAI,OAAO,MAAM,CAAC,UAAU,KAAK,UAAU,GAAG,MAAM,CAAC,UAAU,CAAC,KAAK,CAAC,CAAC,OAAO,GAAG,KAAK,CAAC;IAE9I,MAAM,CAAC,OAAO,EAAE,UAAU,CAAC,GAAGA,cAAQ,CAAC,UAAU,CAAC;IAElDC,eAAS,CAAC,MAAK;AACb,QAAA,IAAI,OAAO,MAAM,KAAK,WAAW,IAAI,OAAO,MAAM,CAAC,UAAU,KAAK,UAAU,EAAE;YAC5E,UAAU,CAAC,KAAK,CAAC;YACjB;QACF;QAEA,MAAM,UAAU,GAAG,MAAM,CAAC,UAAU,CAAC,KAAK,CAAC;AAE3C,QAAA,UAAU,CAAC,UAAU,CAAC,OAAO,CAAC;AAE9B,QAAA,MAAM,YAAY,GAAG,CAAC,KAA0B,KAAK,UAAU,CAAC,KAAK,CAAC,OAAO,CAAC;AAE9E,QAAA,UAAU,CAAC,gBAAgB,CAAC,QAAQ,EAAE,YAAY,CAAC;QACnD,OAAO,MAAM,UAAU,CAAC,mBAAmB,CAAC,QAAQ,EAAE,YAAY,CAAC;AACrE,IAAA,CAAC,EAAE,CAAC,KAAK,CAAC,CAAC;AAEX,IAAA,OAAO,OAAO;AAChB;;;;"}

package/dist/hooks/useBreakpoints/index.d.ts

@@ -0,0 +1,19 @@
+declare const screens: {
+    readonly sm: "640px";
+    readonly md: "768px";
+    readonly lg: "1024px";
+    readonly xl: "1280px";
+    readonly '2xl': "1536px";
+};
+type Breakpoint = keyof typeof screens;
+/**
+ * Checks whether a particular Tailwind CSS viewport size applies.
+ *
+ * @param size The size to check, which must either be included in Tailwind CSS's
+ * list of default screen sizes, or added to the Tailwind CSS config file.
+ *
+ * @returns A boolean indicating whether the viewport size applies.
+ */
+export declare const useBreakpoint: (size: Breakpoint) => boolean;
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/hooks/useBreakpoints/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/hooks/useBreakpoints/index.ts"],"names":[],"mappings":"AAEA,QAAA,MAAM,OAAO;;;;;;CAMH,CAAC;AAEX,KAAK,UAAU,GAAG,MAAM,OAAO,OAAO,CAAC;AAEvC;;;;;;;GAOG;AACH,eAAO,MAAM,aAAa,GAAI,MAAM,UAAU,YAwB7C,CAAC"}

package/dist/hooks/useBreakpoints/index.js

@@ -0,0 +1,37 @@
+import { useState, useEffect } from 'react';
+
+const screens = {
+    sm: '640px',
+    md: '768px',
+    lg: '1024px',
+    xl: '1280px',
+    '2xl': '1536px',
+};
+/**
+ * Checks whether a particular Tailwind CSS viewport size applies.
+ *
+ * @param size The size to check, which must either be included in Tailwind CSS's
+ * list of default screen sizes, or added to the Tailwind CSS config file.
+ *
+ * @returns A boolean indicating whether the viewport size applies.
+ */
+const useBreakpoint = (size) => {
+    const query = `(min-width: ${screens[size]})`;
+    const getMatches = () => (typeof window !== 'undefined' && typeof window.matchMedia === 'function' ? window.matchMedia(query).matches : false);
+    const [matches, setMatches] = useState(getMatches);
+    useEffect(() => {
+        if (typeof window === 'undefined' || typeof window.matchMedia !== 'function') {
+            setMatches(false);
+            return;
+        }
+        const breakpoint = window.matchMedia(query);
+        setMatches(breakpoint.matches);
+        const handleChange = (value) => setMatches(value.matches);
+        breakpoint.addEventListener('change', handleChange);
+        return () => breakpoint.removeEventListener('change', handleChange);
+    }, [query]);
+    return matches;
+};
+
+export { useBreakpoint };
+//# sourceMappingURL=index.js.map

package/dist/hooks/useBreakpoints/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sources":["../../../src/hooks/useBreakpoints/index.ts"],"sourcesContent":[null],"names":[],"mappings":";;AAEA,MAAM,OAAO,GAAG;AACd,IAAA,EAAE,EAAE,OAAO;AACX,IAAA,EAAE,EAAE,OAAO;AACX,IAAA,EAAE,EAAE,QAAQ;AACZ,IAAA,EAAE,EAAE,QAAQ;AACZ,IAAA,KAAK,EAAE,QAAQ;CACP;AAIV;;;;;;;AAOG;AACI,MAAM,aAAa,GAAG,CAAC,IAAgB,KAAI;IAChD,MAAM,KAAK,GAAG,CAAA,YAAA,EAAe,OAAO,CAAC,IAAI,CAAC,GAAG;AAE7C,IAAA,MAAM,UAAU,GAAG,OAAO,OAAO,MAAM,KAAK,WAAW,IAAI,OAAO,MAAM,CAAC,UAAU,KAAK,UAAU,GAAG,MAAM,CAAC,UAAU,CAAC,KAAK,CAAC,CAAC,OAAO,GAAG,KAAK,CAAC;IAE9I,MAAM,CAAC,OAAO,EAAE,UAAU,CAAC,GAAG,QAAQ,CAAC,UAAU,CAAC;IAElD,SAAS,CAAC,MAAK;AACb,QAAA,IAAI,OAAO,MAAM,KAAK,WAAW,IAAI,OAAO,MAAM,CAAC,UAAU,KAAK,UAAU,EAAE;YAC5E,UAAU,CAAC,KAAK,CAAC;YACjB;QACF;QAEA,MAAM,UAAU,GAAG,MAAM,CAAC,UAAU,CAAC,KAAK,CAAC;AAE3C,QAAA,UAAU,CAAC,UAAU,CAAC,OAAO,CAAC;AAE9B,QAAA,MAAM,YAAY,GAAG,CAAC,KAA0B,KAAK,UAAU,CAAC,KAAK,CAAC,OAAO,CAAC;AAE9E,QAAA,UAAU,CAAC,gBAAgB,CAAC,QAAQ,EAAE,YAAY,CAAC;QACnD,OAAO,MAAM,UAAU,CAAC,mBAAmB,CAAC,QAAQ,EAAE,YAAY,CAAC;AACrE,IAAA,CAAC,EAAE,CAAC,KAAK,CAAC,CAAC;AAEX,IAAA,OAAO,OAAO;AAChB;;;;"}

package/dist/hooks/useClipboard/index.cjs

@@ -0,0 +1,70 @@
+'use strict';
+
+var React = require('react');
+
+const DEFAULT_TIMEOUT = 2000;
+/**
+ * Custom hook to copy text to the clipboard.
+ *
+ * @returns {UseClipboardReturnType} - An object containing the copied state and the copy function.
+ */
+const useClipboard = () => {
+    const [copied, setCopied] = React.useState(false);
+    const resetTimerRef = React.useRef(null);
+    const scheduleReset = () => {
+        if (resetTimerRef.current)
+            clearTimeout(resetTimerRef.current);
+        resetTimerRef.current = setTimeout(() => setCopied(false), DEFAULT_TIMEOUT);
+    };
+    React.useEffect(() => {
+        return () => {
+            if (resetTimerRef.current)
+                clearTimeout(resetTimerRef.current);
+        };
+    }, []);
+    // Fallback function for older browsers
+    const fallback = (text, id) => {
+        try {
+            // Textarea to copy the text to the clipboard
+            const textArea = document.createElement('textarea');
+            textArea.value = text;
+            textArea.style.position = 'absolute';
+            textArea.style.left = '-99999px';
+            document.body.appendChild(textArea);
+            textArea.select();
+            const success = document.execCommand('copy');
+            textArea.remove();
+            if (success) {
+                setCopied(id || true);
+                scheduleReset();
+            }
+            return success ? { success: true } : { success: false, error: new Error('execCommand returned false') };
+        }
+        catch (err) {
+            return {
+                success: false,
+                error: err instanceof Error ? err : new Error('Fallback copy failed'),
+            };
+        }
+    };
+    // biome-ignore lint/correctness/useExhaustiveDependencies: We need to return the copied state and the copy function
+    const copy = React.useCallback(async (text, id) => {
+        if (navigator.clipboard && window.isSecureContext) {
+            try {
+                await navigator.clipboard.writeText(text);
+                setCopied(id || true);
+                scheduleReset();
+                return { success: true };
+            }
+            catch (_err) {
+                // If modern method fails, try fallback
+                return fallback(text, id);
+            }
+        }
+        return fallback(text, id);
+    }, []);
+    return { copied, copy };
+};
+
+exports.useClipboard = useClipboard;
+//# sourceMappingURL=index.cjs.map

package/dist/hooks/useClipboard/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.cjs","sources":["../../../src/hooks/useClipboard/index.ts"],"sourcesContent":[null],"names":["useState","useRef","useEffect","useCallback"],"mappings":";;;;AAEA,MAAM,eAAe,GAAG,IAAI;AAqB5B;;;;AAIG;AACI,MAAM,YAAY,GAAG,MAA6B;IACvD,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,GAAGA,cAAQ,CAAmB,KAAK,CAAC;AAC7D,IAAA,MAAM,aAAa,GAAGC,YAAM,CAAuC,IAAI,CAAC;IAExE,MAAM,aAAa,GAAG,MAAK;QACzB,IAAI,aAAa,CAAC,OAAO;AAAE,YAAA,YAAY,CAAC,aAAa,CAAC,OAAO,CAAC;AAC9D,QAAA,aAAa,CAAC,OAAO,GAAG,UAAU,CAAC,MAAM,SAAS,CAAC,KAAK,CAAC,EAAE,eAAe,CAAC;AAC7E,IAAA,CAAC;IAEDC,eAAS,CAAC,MAAK;AACb,QAAA,OAAO,MAAK;YACV,IAAI,aAAa,CAAC,OAAO;AAAE,gBAAA,YAAY,CAAC,aAAa,CAAC,OAAO,CAAC;AAChE,QAAA,CAAC;IACH,CAAC,EAAE,EAAE,CAAC;;AAGN,IAAA,MAAM,QAAQ,GAAG,CAAC,IAAY,EAAE,EAAW,KAAI;AAC7C,QAAA,IAAI;;YAEF,MAAM,QAAQ,GAAG,QAAQ,CAAC,aAAa,CAAC,UAAU,CAAC;AACnD,YAAA,QAAQ,CAAC,KAAK,GAAG,IAAI;AACrB,YAAA,QAAQ,CAAC,KAAK,CAAC,QAAQ,GAAG,UAAU;AACpC,YAAA,QAAQ,CAAC,KAAK,CAAC,IAAI,GAAG,UAAU;AAEhC,YAAA,QAAQ,CAAC,IAAI,CAAC,WAAW,CAAC,QAAQ,CAAC;YACnC,QAAQ,CAAC,MAAM,EAAE;YAEjB,MAAM,OAAO,GAAG,QAAQ,CAAC,WAAW,CAAC,MAAM,CAAC;YAC5C,QAAQ,CAAC,MAAM,EAAE;YAEjB,IAAI,OAAO,EAAE;AACX,gBAAA,SAAS,CAAC,EAAE,IAAI,IAAI,CAAC;AACrB,gBAAA,aAAa,EAAE;YACjB;YAEA,OAAO,OAAO,GAAG,EAAE,OAAO,EAAE,IAAI,EAAE,GAAG,EAAE,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,IAAI,KAAK,CAAC,4BAA4B,CAAC,EAAE;QACzG;QAAE,OAAO,GAAG,EAAE;YACZ,OAAO;AACL,gBAAA,OAAO,EAAE,KAAK;AACd,gBAAA,KAAK,EAAE,GAAG,YAAY,KAAK,GAAG,GAAG,GAAG,IAAI,KAAK,CAAC,sBAAsB,CAAC;aACtE;QACH;AACF,IAAA,CAAC;;IAGD,MAAM,IAAI,GAAGC,iBAAW,CAAC,OAAO,IAAY,EAAE,EAAW,KAAI;QAC3D,IAAI,SAAS,CAAC,SAAS,IAAI,MAAM,CAAC,eAAe,EAAE;AACjD,YAAA,IAAI;gBACF,MAAM,SAAS,CAAC,SAAS,CAAC,SAAS,CAAC,IAAI,CAAC;AAEzC,gBAAA,SAAS,CAAC,EAAE,IAAI,IAAI,CAAC;AACrB,gBAAA,aAAa,EAAE;AAEf,gBAAA,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE;YAC1B;YAAE,OAAO,IAAI,EAAE;;AAEb,gBAAA,OAAO,QAAQ,CAAC,IAAI,EAAE,EAAE,CAAC;YAC3B;QACF;AACA,QAAA,OAAO,QAAQ,CAAC,IAAI,EAAE,EAAE,CAAC;IAC3B,CAAC,EAAE,EAAE,CAAC;AAEN,IAAA,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE;AACzB;;;;"}

package/dist/hooks/useClipboard/index.d.ts

@@ -0,0 +1,29 @@
+type UseClipboardReturnType = {
+    /**
+     * The state indicating whether the text has been copied.
+     * If a string is provided, it will be used as the identifier for the copied state.
+     */
+    copied: string | boolean;
+    /**
+     * Function to copy text to the clipboard using the modern clipboard API.
+     * Falls back to the fallback function if the modern API fails.
+     *
+     * @param {string} text - The text to be copied.
+     * @param {string} [id] - Optional identifier to set the copied state.
+     * @returns {Promise<Object>} - A promise that resolves to an object containing:
+     *  - `success` (boolean): Whether the copy operation was successful.
+     *  - `error` (Error | undefined): The error object if the copy operation failed.
+     */
+    copy: (text: string, id?: string) => Promise<{
+        success: boolean;
+        error?: Error;
+    }>;
+};
+/**
+ * Custom hook to copy text to the clipboard.
+ *
+ * @returns {UseClipboardReturnType} - An object containing the copied state and the copy function.
+ */
+export declare const useClipboard: () => UseClipboardReturnType;
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/hooks/useClipboard/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/hooks/useClipboard/index.ts"],"names":[],"mappings":"AAIA,KAAK,sBAAsB,GAAG;IAC5B;;;OAGG;IACH,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC;IACzB;;;;;;;;;OASG;IACH,IAAI,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,CAAC,EAAE,MAAM,KAAK,OAAO,CAAC;QAAE,OAAO,EAAE,OAAO,CAAC;QAAC,KAAK,CAAC,EAAE,KAAK,CAAA;KAAE,CAAC,CAAC;CACnF,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,YAAY,QAAO,sBA+D/B,CAAC"}