@beautinique/frontend-components 0.0.0-stage → 1.0.1

package/README.md

@@ -1,3 +1,101 @@
-# Temporary Holding Version
+# @beautinique/frontend-components
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Shared React UI components for the Beautinique frontends (Vite + React 19 + Tailwind v4).
+
+The components are styled with Tailwind classes and with the tokens (colours, shadows, fonts) of
+[`@beautinique/frontend-styles`](../styles/README.md), so an app needs both.
+
+## Installation
+
+```bash
+npm install @beautinique/frontend-components @beautinique/frontend-styles @iconify/react
+```
+
+Peer dependencies: `react`, `react-dom`, `@iconify/react`, `@beautinique/frontend-styles`.
+
+## Setup (once per app)
+
+In the app's own `index.css`, in this order:
+
+```css
+@import '@beautinique/frontend-styles';
+@import '@beautinique/frontend-components/source.css';
+@import './app.css';
+```
+
+`source.css` is not optional. Tailwind v4 does not look for class names inside `node_modules`, so
+without it the classes the components use (`rounded-lg`, `shadow-primary-btn`, ...) are never
+generated and the components come out unstyled. (The playground has a page that shows exactly that.)
+
+## Import paths
+
+Components that most screens use live in `/ui` (and, later, `/layout`). Components that few screens
+use have a path of their own, so an app only bundles what it imports.
+
+| Import path                                   | What it gives                                                                                |
+| --------------------------------------------- | -------------------------------------------------------------------------------------------- |
+| `@beautinique/frontend-components`            | Types only (`IButton`, `ITooltip`, ...)                                                      |
+| `@beautinique/frontend-components/ui`         | `Button`, `Tooltip`                                                                          |
+| `@beautinique/frontend-components/toast`      | `ToastContainer`, `toaster`, the toast store, and the helpers for toasts that follow uploads |
+| `@beautinique/frontend-components/source.css` | The `@source` line of the setup above                                                        |
+
+```tsx
+import { Button, Tooltip } from '@beautinique/frontend-components/ui';
+import { ToastContainer, toaster } from '@beautinique/frontend-components/toast';
+
+const App = () => (
+  <>
+    <ToastContainer /> {/* once, near the root of the app */}
+    <Tooltip title="Save" description="Ctrl + S">
+      <Button
+        pattern="primary"
+        content="Save"
+        buttonProps={{ onClick: () => toaster.success({ title: 'Saved' }) }}
+      />
+    </Tooltip>
+  </>
+);
+```
+
+### Toasts
+
+`toaster` works from anywhere (an API client, a store), not only from components:
+
+```ts
+toaster.success({ title: 'Saved', description: 'Your changes were saved.' });
+toaster.error({ title: 'Failed' });
+toaster.warning({ title: 'Careful' });
+toaster.loading({ title: 'Working' });
+```
+
+Toasts that follow uploads (`withProgressToast` for one request, `createUploadsToast`,
+`withUploadsToast` and `runUploadsInToast` for several) are described in `src/toast/uploads.ts`.
+`runUploadsInToast` shows one toast for the uploads of several fields: the overall progress on the
+left and a row (waiting, uploading, done or failed) for each field that has files.
+
+The icons of the toasts are bundled, so a toast shows its icon without a network.
+
+## Rules for the code of this package
+
+- **State lives in exactly one import path.** The toast store is part of `/toast` only. A component
+  of another path that needs it must import it from `@beautinique/frontend-components/toast`, never
+  copy it: every entry is built as one file, so a copy would be a second store, and a toast shown
+  through it would never reach the `ToastContainer`.
+- **A component's own css lives next to the component** and is imported by it, not by the styles
+  package. It uses the variables of the styles package (`var(--smoke-eerie)`, ...) and does not
+  import them again: importing them a second time, after the app's own css, would undo the app's
+  overrides.
+- **No imports from an app.** What a component needs from its app comes in through props.
+
+## Development
+
+```bash
+npm run build        # dist (needed by the playground and by the type check of the playground)
+npm run playground   # http://localhost:4200 - the components, in a real browser
+npm test
+```
+
+After a rebuild of `dist` restart the playground (or touch `playground/index.css`): Tailwind looks for class names in `dist` when the css is processed, so a class that is new in `dist` is not generated until then. An app that installs the package from npm does not have this, it builds with the package as it is.
+
+The playground (`playground/`) is a small Vite page that uses the package through its public import
+paths, the way an app does. It is not published (`files` in `package.json` leaves it out).

package/dist/index.cjs

@@ -0,0 +1,4 @@
+'use strict';
+
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"index.cjs"}

package/dist/index.d.cts

@@ -0,0 +1,2 @@
+export type * from './types/component.js';
+//# sourceMappingURL=index.d.cts.map

package/dist/index.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.cts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,mBAAmB,sBAAsB,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export type * from './types/component.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,mBAAmB,sBAAsB,CAAC"}

package/dist/index.js

@@ -0,0 +1,3 @@
+
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"index.js"}

package/dist/lib/button.d.cts

@@ -0,0 +1,3 @@
+import type { IButton } from '../types/component.js';
+export declare const getButtonCss: (pattern: IButton["pattern"]) => "text-white bg-sky-blue-burst shadow-primary-btn hover:shadow-primary-btn-hover" | "text-secondary-invert bg-secondary shadow-secondary-btn hover:shadow-secondary-btn-hover" | "text-tertiary-invert bg-tertiary shadow-tertiary-btn hover:shadow-tertiary-btn-hover" | "text-primary border border-primary shadow-outline-btn hover:shadow-outline-btn-hover" | "bg-transparent border border-primary/30 text-secondary";
+//# sourceMappingURL=button.d.cts.map

package/dist/lib/button.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"button.d.cts","sourceRoot":"","sources":["../../src/lib/button.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,uBAAuB,CAAC;AAErD,eAAO,MAAM,YAAY,GAAI,SAAS,OAAO,CAAC,SAAS,CAAC,+ZAcvD,CAAC"}

package/dist/lib/button.d.ts

@@ -0,0 +1,3 @@
+import type { IButton } from '../types/component.js';
+export declare const getButtonCss: (pattern: IButton["pattern"]) => "text-white bg-sky-blue-burst shadow-primary-btn hover:shadow-primary-btn-hover" | "text-secondary-invert bg-secondary shadow-secondary-btn hover:shadow-secondary-btn-hover" | "text-tertiary-invert bg-tertiary shadow-tertiary-btn hover:shadow-tertiary-btn-hover" | "text-primary border border-primary shadow-outline-btn hover:shadow-outline-btn-hover" | "bg-transparent border border-primary/30 text-secondary";
+//# sourceMappingURL=button.d.ts.map

package/dist/lib/button.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"button.d.ts","sourceRoot":"","sources":["../../src/lib/button.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,uBAAuB,CAAC;AAErD,eAAO,MAAM,YAAY,GAAI,SAAS,OAAO,CAAC,SAAS,CAAC,+ZAcvD,CAAC"}

package/dist/lib/constants.d.cts

@@ -0,0 +1,5 @@
+export declare const TOOLTIP_GAP: 15;
+export declare const TOOLTIP_ANIMATION_DURATION: 400;
+export declare const TOAST_TYPES: readonly ["success", "error", "warning", "progress", "uploads", "loading", "default", "custom"];
+export declare const TOAST_TYPE: { [K in (typeof TOAST_TYPES)[number]]: K; };
+//# sourceMappingURL=constants.d.cts.map

package/dist/lib/constants.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.d.cts","sourceRoot":"","sources":["../../src/lib/constants.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,WAAW,EAAG,EAAW,CAAC;AACvC,eAAO,MAAM,0BAA0B,EAAG,GAAY,CAAC;AAEvD,eAAO,MAAM,WAAW,iGASd,CAAC;AAEX,eAAO,MAAM,UAAU,EAAkE,GACtF,CAAC,IAAI,CAAC,OAAO,WAAW,EAAE,MAAM,CAAC,GAAG,CAAC,GACvC,CAAC"}

package/dist/lib/constants.d.ts

@@ -0,0 +1,5 @@
+export declare const TOOLTIP_GAP: 15;
+export declare const TOOLTIP_ANIMATION_DURATION: 400;
+export declare const TOAST_TYPES: readonly ["success", "error", "warning", "progress", "uploads", "loading", "default", "custom"];
+export declare const TOAST_TYPE: { [K in (typeof TOAST_TYPES)[number]]: K; };
+//# sourceMappingURL=constants.d.ts.map

package/dist/lib/constants.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../../src/lib/constants.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,WAAW,EAAG,EAAW,CAAC;AACvC,eAAO,MAAM,0BAA0B,EAAG,GAAY,CAAC;AAEvD,eAAO,MAAM,WAAW,iGASd,CAAC;AAEX,eAAO,MAAM,UAAU,EAAkE,GACtF,CAAC,IAAI,CAAC,OAAO,WAAW,EAAE,MAAM,CAAC,GAAG,CAAC,GACvC,CAAC"}

package/dist/lib/tooltip.d.cts

@@ -0,0 +1,6 @@
+import type { CSSProperties } from 'react';
+import type { ITooltip } from '../types/component.js';
+export declare const getTooltipPosition: (rect: DOMRect, placement: NonNullable<ITooltip["placement"]>) => CSSProperties;
+export declare const getTooltipTransform: (placement: NonNullable<ITooltip["placement"]>, isVisible: boolean) => string;
+export declare const getTooltipArrowCss: (placement: NonNullable<ITooltip["placement"]>) => "after:bottom-full after:left-1/2 after:-translate-x-1/2 after:border-b-silver-jet-2" | "after:top-1/2 after:right-full after:-translate-y-1/2 after:border-r-silver-jet-2" | "after:top-1/2 after:left-full after:-translate-y-1/2 after:border-l-silver-jet-2" | "after:top-full after:left-1/2 after:-translate-x-1/2 after:border-t-silver-jet-2";
+//# sourceMappingURL=tooltip.d.cts.map

package/dist/lib/tooltip.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tooltip.d.cts","sourceRoot":"","sources":["../../src/lib/tooltip.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,OAAO,CAAC;AAE3C,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AAGtD,eAAO,MAAM,kBAAkB,GAC7B,MAAM,OAAO,EACb,WAAW,WAAW,CAAC,QAAQ,CAAC,WAAW,CAAC,CAAC,KAC5C,aAYF,CAAC;AAEF,eAAO,MAAM,mBAAmB,GAC9B,WAAW,WAAW,CAAC,QAAQ,CAAC,WAAW,CAAC,CAAC,EAC7C,WAAW,OAAO,WAenB,CAAC;AAEF,eAAO,MAAM,kBAAkB,GAAI,WAAW,WAAW,CAAC,QAAQ,CAAC,WAAW,CAAC,CAAC,0VAY/E,CAAC"}

package/dist/lib/tooltip.d.ts

@@ -0,0 +1,6 @@
+import type { CSSProperties } from 'react';
+import type { ITooltip } from '../types/component.js';
+export declare const getTooltipPosition: (rect: DOMRect, placement: NonNullable<ITooltip["placement"]>) => CSSProperties;
+export declare const getTooltipTransform: (placement: NonNullable<ITooltip["placement"]>, isVisible: boolean) => string;
+export declare const getTooltipArrowCss: (placement: NonNullable<ITooltip["placement"]>) => "after:bottom-full after:left-1/2 after:-translate-x-1/2 after:border-b-silver-jet-2" | "after:top-1/2 after:right-full after:-translate-y-1/2 after:border-r-silver-jet-2" | "after:top-1/2 after:left-full after:-translate-y-1/2 after:border-l-silver-jet-2" | "after:top-full after:left-1/2 after:-translate-x-1/2 after:border-t-silver-jet-2";
+//# sourceMappingURL=tooltip.d.ts.map

package/dist/lib/tooltip.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tooltip.d.ts","sourceRoot":"","sources":["../../src/lib/tooltip.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,OAAO,CAAC;AAE3C,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AAGtD,eAAO,MAAM,kBAAkB,GAC7B,MAAM,OAAO,EACb,WAAW,WAAW,CAAC,QAAQ,CAAC,WAAW,CAAC,CAAC,KAC5C,aAYF,CAAC;AAEF,eAAO,MAAM,mBAAmB,GAC9B,WAAW,WAAW,CAAC,QAAQ,CAAC,WAAW,CAAC,CAAC,EAC7C,WAAW,OAAO,WAenB,CAAC;AAEF,eAAO,MAAM,kBAAkB,GAAI,WAAW,WAAW,CAAC,QAAQ,CAAC,WAAW,CAAC,CAAC,0VAY/E,CAAC"}

package/dist/toast/ToastContainer.d.cts

@@ -0,0 +1,5 @@
+import type { IClassName } from '../types/component.js';
+import type { TToastItem } from './types.js';
+export declare const Toaster: (props: TToastItem & IClassName) => import("react").JSX.Element | null;
+export declare const ToastContainer: () => import("react").JSX.Element | null;
+//# sourceMappingURL=ToastContainer.d.cts.map

package/dist/toast/ToastContainer.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ToastContainer.d.cts","sourceRoot":"","sources":["../../src/toast/ToastContainer.tsx"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAC;AAIxD,OAAO,KAAK,EAAuB,UAAU,EAAqB,MAAM,YAAY,CAAC;AAkLrF,eAAO,MAAM,OAAO,GAAI,OAAO,UAAU,GAAG,UAAU,uCAmJrD,CAAC;AAEF,eAAO,MAAM,cAAc,0CAY1B,CAAC"}

package/dist/toast/ToastContainer.d.ts

@@ -0,0 +1,5 @@
+import type { IClassName } from '../types/component.js';
+import type { TToastItem } from './types.js';
+export declare const Toaster: (props: TToastItem & IClassName) => import("react").JSX.Element | null;
+export declare const ToastContainer: () => import("react").JSX.Element | null;
+//# sourceMappingURL=ToastContainer.d.ts.map

package/dist/toast/ToastContainer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ToastContainer.d.ts","sourceRoot":"","sources":["../../src/toast/ToastContainer.tsx"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAC;AAIxD,OAAO,KAAK,EAAuB,UAAU,EAAqB,MAAM,YAAY,CAAC;AAkLrF,eAAO,MAAM,OAAO,GAAI,OAAO,UAAU,GAAG,UAAU,uCAmJrD,CAAC;AAEF,eAAO,MAAM,cAAc,0CAY1B,CAAC"}