@flipdish/ui-library 0.4.2 → 0.4.3

package/README.md

@@ -15,12 +15,12 @@ Atomic-design React component library for Flipdish products, built on **Tailwind
 ## Installation
 
 ```bash
-pnpm add @flipdish/ui-library
+pnpm add @flipdish/ui-library @flipdish/ui-tokens @flipdish/ui-icons
 ```
 
-### Peer dependencies
+For the full setup walkthrough (Vite config, CSS entry, providers, first component), see [Getting Started → Installation](https://flipdishbytes.github.io/flipdish-design-system/?path=/docs/getting-started-installation--docs).
 
-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).
+### Peer dependencies
 
 **Shared — required on every platform:**
 
@@ -50,7 +50,7 @@ Install the peers for the platform(s) you target. Platform-specific peers are de
 
 ### Component-specific peer dependencies
 
-A handful of components are backed by larger third-party libraries. Those libraries are declared as **optional** peer dependencies so consumers only install what they actually use — importing `Button` never pulls in the charting or rich-text stack. Install the matching peer(s) only for the components you import; if a peer is missing, that component will fail to resolve at build/runtime.
+A handful of components are backed by larger third-party libraries declared as **optional** peers — importing `Button` never pulls in the charting or rich-text stack. Install only the peer(s) for the components you actually use; a missing peer causes a build/runtime error.
 
 | Component                         | Required peer(s)                                                                                                                                                                                 |
 | --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
@@ -63,61 +63,23 @@ A handful of components are backed by larger third-party libraries. Those librar
 | `CommandMenu`                     | `react-hotkeys-hook`                                                                                                                                                                             |
 | `FileUpload`, `SidebarNavigation` | `motion`                                                                                                                                                                                         |
 
-For example, to use the rich-text editor:
-
-```bash
-pnpm add @tiptap/core @tiptap/pm @tiptap/react @tiptap/starter-kit @tiptap/extension-image @tiptap/extension-placeholder @tiptap/extension-text-align @tiptap/extension-text-style
-```
-
 ## Tailwind setup
 
-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:
+Import the library's shared runtime from your CSS entry **in this exact layer order**:
 
 ```css
 @layer theme, base, components, utilities;
 
 @import "tailwindcss/theme.css" layer(theme);
-@import "@flipdish/ui-tokens/css" layer(theme); /* tokens + [data-theme="dark"] */
+@import "@flipdish/ui-tokens/css" layer(theme);
 @import "tailwindcss/preflight.css" layer(base);
-@import "@flipdish/ui-library/styles"; /* plugins, variants, @utility, resets */
+@import "@flipdish/ui-library/styles";
 @import "tailwindcss/utilities.css" layer(utilities);
 ```
 
-The library ships pre-built — compiled ESM and CommonJS with TypeScript declarations — so each subpath resolves to built output in `dist/`.
-
-## Usage
-
-Components, providers, hooks, and utilities are imported from subpaths that mirror the atomic-design layers:
-
-```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";
-
-// 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";
-
-// Hooks
-import { useBreakpoint } from "@flipdish/ui-library/hooks/useBreakpoints";
-import { useClipboard } from "@flipdish/ui-library/hooks/useClipboard";
-
-// Utilities
-import { cx, sortCx } from "@flipdish/ui-library/utilities/cx";
-```
-
-### Styling rules
-
-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.
-
-## Platform support (web + React Native)
-
-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.
-
-`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`.
+## Documentation
 
-**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.
+Full component docs, interactive examples, and design guidance live in the [Storybook](https://flipdishbytes.github.io/flipdish-design-system/).
 
 ## Changelog
 

package/dist/providers/UIProvider/index.cjs

@@ -0,0 +1,29 @@
+'use strict';
+
+var jsxRuntime = require('react/jsx-runtime');
+var RouteProvider = require('@flipdish/ui-library/providers/RouteProvider');
+var ThemeProvider = require('@flipdish/ui-library/providers/ThemeProvider');
+var reactRouter = require('react-router');
+
+/**
+ * @summary single entry-point provider that composes the Flipdish UI providers (theme, routing, and — soon — translations)
+ */
+const UIProvider = ({ children, themeModeOverride, withBrowserRouter = true, withRouteProvider = true, }) => {
+    let tree = children;
+    // RouteProvider must sit inside a router; keep it innermost so it can bind to
+    // either our BrowserRouter or a host-owned one.
+    if (withRouteProvider) {
+        tree = jsxRuntime.jsx(RouteProvider.RouteProvider, { children: tree });
+    }
+    if (withBrowserRouter) {
+        tree = jsxRuntime.jsx(reactRouter.BrowserRouter, { children: tree });
+    }
+    // TODO(i18n): wrap `tree` in <TranslationProvider> once the translation layer lands.
+    // It will likely expose an async `useLoadTranslations(languageOverride)` hook (see
+    // FlipdishUI's FlipdishUIProvider) and a `languageOverride` prop forwarded from here.
+    // Order: ThemeProvider > [BrowserRouter > RouteProvider] > TranslationProvider > children.
+    return jsxRuntime.jsx(ThemeProvider.ThemeProvider, { themeModeOverride: themeModeOverride, children: tree });
+};
+
+exports.UIProvider = UIProvider;
+//# sourceMappingURL=index.cjs.map

package/dist/providers/UIProvider/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.cjs","sources":["../../../src/providers/UIProvider/index.tsx"],"sourcesContent":[null],"names":["_jsx","RouteProvider","BrowserRouter","ThemeProvider"],"mappings":";;;;;;;AA4BA;;AAEG;AACI,MAAM,UAAU,GAAG,CAAC,EACzB,QAAQ,EACR,iBAAiB,EACjB,iBAAiB,GAAG,IAAI,EACxB,iBAAiB,GAAG,IAAI,GACW,KAAI;IACvC,IAAI,IAAI,GAAG,QAAQ;;;IAInB,IAAI,iBAAiB,EAAE;AACrB,QAAA,IAAI,GAAGA,cAAA,CAACC,2BAAa,EAAA,EAAA,QAAA,EAAE,IAAI,GAAiB;IAC9C;IAEA,IAAI,iBAAiB,EAAE;AACrB,QAAA,IAAI,GAAGD,cAAA,CAACE,yBAAa,EAAA,EAAA,QAAA,EAAE,IAAI,GAAiB;IAC9C;;;;;IAMA,OAAOF,cAAA,CAACG,2BAAa,EAAA,EAAC,iBAAiB,EAAE,iBAAiB,EAAA,QAAA,EAAG,IAAI,EAAA,CAAiB;AACpF;;;;"}

package/dist/providers/UIProvider/index.d.ts

@@ -0,0 +1,28 @@
+import type { PropsWithChildren } from 'react';
+export interface UIProviderProps {
+    /**
+     * Controlled theme override. When set, the tree renders in this mode and theme
+     * persistence is skipped. Omit to use ThemeProvider's own light/dark/system logic.
+     */
+    themeModeOverride?: 'light' | 'dark';
+    /**
+     * Render a `BrowserRouter`. Set `false` when a host/parent app already owns a
+     * router (e.g. a micro-frontend mounted in a shell, or an app using react-router's
+     * data APIs via `createBrowserRouter`) — a second router would fight over the URL.
+     * @default true
+     */
+    withBrowserRouter?: boolean;
+    /**
+     * Wire react-aria-components navigation into react-router (so `<Link>`, etc. use
+     * client-side navigation). Keep `true` even when `withBrowserRouter` is `false`, so
+     * react-aria routing binds to the host's router. Set `false` only for non-routed
+     * surfaces (single-screen apps, some test/Storybook setups).
+     * @default true
+     */
+    withRouteProvider?: boolean;
+}
+/**
+ * @summary single entry-point provider that composes the Flipdish UI providers (theme, routing, and — soon — translations)
+ */
+export declare const UIProvider: ({ children, themeModeOverride, withBrowserRouter, withRouteProvider, }: PropsWithChildren<UIProviderProps>) => import("react").JSX.Element;
+//# sourceMappingURL=index.d.ts.map

package/dist/providers/UIProvider/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/providers/UIProvider/index.tsx"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,OAAO,CAAC;AAG/C,MAAM,WAAW,eAAe;IAC9B;;;OAGG;IACH,iBAAiB,CAAC,EAAE,OAAO,GAAG,MAAM,CAAC;IACrC;;;;;OAKG;IACH,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B;;;;;;OAMG;IACH,iBAAiB,CAAC,EAAE,OAAO,CAAC;CAC7B;AAED;;GAEG;AACH,eAAO,MAAM,UAAU,GAAI,wEAKxB,iBAAiB,CAAC,eAAe,CAAC,gCAkBpC,CAAC"}

package/dist/providers/UIProvider/index.js

@@ -0,0 +1,27 @@
+import { jsx } from 'react/jsx-runtime';
+import { RouteProvider } from '@flipdish/ui-library/providers/RouteProvider';
+import { ThemeProvider } from '@flipdish/ui-library/providers/ThemeProvider';
+import { BrowserRouter } from 'react-router';
+
+/**
+ * @summary single entry-point provider that composes the Flipdish UI providers (theme, routing, and — soon — translations)
+ */
+const UIProvider = ({ children, themeModeOverride, withBrowserRouter = true, withRouteProvider = true, }) => {
+    let tree = children;
+    // RouteProvider must sit inside a router; keep it innermost so it can bind to
+    // either our BrowserRouter or a host-owned one.
+    if (withRouteProvider) {
+        tree = jsx(RouteProvider, { children: tree });
+    }
+    if (withBrowserRouter) {
+        tree = jsx(BrowserRouter, { children: tree });
+    }
+    // TODO(i18n): wrap `tree` in <TranslationProvider> once the translation layer lands.
+    // It will likely expose an async `useLoadTranslations(languageOverride)` hook (see
+    // FlipdishUI's FlipdishUIProvider) and a `languageOverride` prop forwarded from here.
+    // Order: ThemeProvider > [BrowserRouter > RouteProvider] > TranslationProvider > children.
+    return jsx(ThemeProvider, { themeModeOverride: themeModeOverride, children: tree });
+};
+
+export { UIProvider };
+//# sourceMappingURL=index.js.map

package/dist/providers/UIProvider/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sources":["../../../src/providers/UIProvider/index.tsx"],"sourcesContent":[null],"names":["_jsx"],"mappings":";;;;;AA4BA;;AAEG;AACI,MAAM,UAAU,GAAG,CAAC,EACzB,QAAQ,EACR,iBAAiB,EACjB,iBAAiB,GAAG,IAAI,EACxB,iBAAiB,GAAG,IAAI,GACW,KAAI;IACvC,IAAI,IAAI,GAAG,QAAQ;;;IAInB,IAAI,iBAAiB,EAAE;AACrB,QAAA,IAAI,GAAGA,GAAA,CAAC,aAAa,EAAA,EAAA,QAAA,EAAE,IAAI,GAAiB;IAC9C;IAEA,IAAI,iBAAiB,EAAE;AACrB,QAAA,IAAI,GAAGA,GAAA,CAAC,aAAa,EAAA,EAAA,QAAA,EAAE,IAAI,GAAiB;IAC9C;;;;;IAMA,OAAOA,GAAA,CAAC,aAAa,EAAA,EAAC,iBAAiB,EAAE,iBAAiB,EAAA,QAAA,EAAG,IAAI,EAAA,CAAiB;AACpF;;;;"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flipdish/ui-library",
-  "version": "0.4.2",
+  "version": "0.4.3",
   "description": "Flipdish Design System — atomic-design component library (Tailwind v4 + UntitledUI + React Aria).",
   "type": "module",
   "sideEffects": [