@flipdish/ui-library 0.4.2 → 0.5.0

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,21 @@
+'use strict';
+
+var jsxRuntime = require('react/jsx-runtime');
+var ErrorBoundary = require('@flipdish/ui-library/providers/ErrorBoundary');
+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 theme, routing, and an error boundary for consuming apps
+ */
+const UIProvider = ({ children, themeModeOverride, baseUrl, errorBoundary }) => {
+    // TODO(i18n): add an internal library translation context so ui-library components can
+    // source their own copy (e.g. ErrorBoundary's "Something went wrong") without the
+    // consuming app needing to pass text props. This is purely internal — consuming apps
+    // own their own translation layer and wrap their content inside UIProvider as usual.
+    return (jsxRuntime.jsx(ThemeProvider.ThemeProvider, { themeModeOverride: themeModeOverride, children: jsxRuntime.jsx(reactRouter.BrowserRouter, { basename: baseUrl, children: jsxRuntime.jsx(RouteProvider.RouteProvider, { children: jsxRuntime.jsx(ErrorBoundary.ErrorBoundary, { ...errorBoundary, children: children }) }) }) }));
+};
+
+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","ThemeProvider","BrowserRouter","RouteProvider","ErrorBoundary"],"mappings":";;;;;;;;AA4BA;;AAEG;AACI,MAAM,UAAU,GAAG,CAAC,EAAE,QAAQ,EAAE,iBAAiB,EAAE,OAAO,EAAE,aAAa,EAAsC,KAAI;;;;;AAKxH,IAAA,QACEA,cAAA,CAACC,2BAAa,EAAA,EAAC,iBAAiB,EAAE,iBAAiB,EAAA,QAAA,EACjDD,cAAA,CAACE,yBAAa,EAAA,EAAC,QAAQ,EAAE,OAAO,EAAA,QAAA,EAC9BF,cAAA,CAACG,2BAAa,EAAA,EAAA,QAAA,EACZH,cAAA,CAACI,2BAAa,EAAA,EAAA,GAAK,aAAa,EAAA,QAAA,EAAG,QAAQ,EAAA,CAAiB,EAAA,CAC9C,EAAA,CACF,EAAA,CACF;AAEpB;;;;"}

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

@@ -0,0 +1,28 @@
+import { type ErrorBoundaryProps } from '@flipdish/ui-library/providers/ErrorBoundary';
+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';
+    /**
+     * Base URL for the internal router. Use for micro-frontends mounted at a sub-path
+     * (e.g. `getMicroFrontendAttribute('data-portal-base-url') || '/'`).
+     */
+    baseUrl?: string;
+    /**
+     * Props for the app-level `ErrorBoundary` that wraps children.
+     * At minimum pass `identifier` (e.g. `'app'`) to label the boundary in error
+     * logs. Wire `onError` to your error reporter (Datadog RUM, fdlogger, etc.).
+     *
+     * @example
+     * errorBoundary={{ identifier: 'app', onError: datadogReporter }}
+     */
+    errorBoundary: Omit<ErrorBoundaryProps, 'children'>;
+}
+/**
+ * @summary single entry-point provider that composes theme, routing, and an error boundary for consuming apps
+ */
+export declare const UIProvider: ({ children, themeModeOverride, baseUrl, errorBoundary }: 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":"AAAA,OAAO,EAAiB,KAAK,kBAAkB,EAAE,MAAM,8CAA8C,CAAC;AAGtG,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,OAAO,CAAC;AAG/C,MAAM,WAAW,eAAe;IAC9B;;;OAGG;IACH,iBAAiB,CAAC,EAAE,OAAO,GAAG,MAAM,CAAC;IACrC;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;;;;;OAOG;IACH,aAAa,EAAE,IAAI,CAAC,kBAAkB,EAAE,UAAU,CAAC,CAAC;CACrD;AAED;;GAEG;AACH,eAAO,MAAM,UAAU,GAAI,yDAAyD,iBAAiB,CAAC,eAAe,CAAC,gCAcrH,CAAC"}

package/dist/providers/UIProvider/index.js

@@ -0,0 +1,19 @@
+import { jsx } from 'react/jsx-runtime';
+import { ErrorBoundary } from '@flipdish/ui-library/providers/ErrorBoundary';
+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 theme, routing, and an error boundary for consuming apps
+ */
+const UIProvider = ({ children, themeModeOverride, baseUrl, errorBoundary }) => {
+    // TODO(i18n): add an internal library translation context so ui-library components can
+    // source their own copy (e.g. ErrorBoundary's "Something went wrong") without the
+    // consuming app needing to pass text props. This is purely internal — consuming apps
+    // own their own translation layer and wrap their content inside UIProvider as usual.
+    return (jsx(ThemeProvider, { themeModeOverride: themeModeOverride, children: jsx(BrowserRouter, { basename: baseUrl, children: jsx(RouteProvider, { children: jsx(ErrorBoundary, { ...errorBoundary, children: children }) }) }) }));
+};
+
+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,EAAE,QAAQ,EAAE,iBAAiB,EAAE,OAAO,EAAE,aAAa,EAAsC,KAAI;;;;;AAKxH,IAAA,QACEA,GAAA,CAAC,aAAa,EAAA,EAAC,iBAAiB,EAAE,iBAAiB,EAAA,QAAA,EACjDA,GAAA,CAAC,aAAa,EAAA,EAAC,QAAQ,EAAE,OAAO,EAAA,QAAA,EAC9BA,GAAA,CAAC,aAAa,EAAA,EAAA,QAAA,EACZA,GAAA,CAAC,aAAa,EAAA,EAAA,GAAK,aAAa,EAAA,QAAA,EAAG,QAAQ,EAAA,CAAiB,EAAA,CAC9C,EAAA,CACF,EAAA,CACF;AAEpB;;;;"}

package/package.json

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