@hemerson/design-system 0.2.0 → 0.3.1

package/README.md

@@ -26,9 +26,37 @@ export function Toolbar() {
 }
 ```
 
-- **Themes:** set `data-theme="dark"` (the default) or `data-theme="light"` on `<html>`.
-- **Reduced transparency:** set `data-transparency="reduced"` on `<html>` to turn every glass surface solid. Offer it as a setting in your app.
+- **Themes and transparency:** apps open dark. Call `applyStoredAppearance()` before the first render to restore what the visitor chose last time, and put `ThemeToggle` and `TransparencyToggle` in your toolbar. Without React, `setTheme` and `setTransparency` do the same job. Under the hood these set `data-theme` and `data-transparency` on `<html>`.
+- **Toasts:** wrap the app in `ToastProvider` and call `useToast()` to stack up to three at a time.
 - **Edge lens:** call `enableGlassRefraction()` from `@hemerson/design-system/glass` once at startup to bend the content at the glass edges in Chromium. Other browsers keep frosted glass.
+
+```ts
+// main.tsx, before the first render, so the page never flashes the wrong theme
+import { applyStoredAppearance } from "@hemerson/design-system/appearance";
+
+applyStoredAppearance();
+```
+
+```tsx
+import { ThemeToggle, TransparencyToggle } from "@hemerson/design-system";
+
+<ThemeToggle />          // dark ↔ light, remembered
+<TransparencyToggle />   // solid glass, remembered
+```
+
+```tsx
+import { ToastProvider, useToast } from "@hemerson/design-system";
+
+<ToastProvider>
+  <App />
+</ToastProvider>;
+
+// anywhere inside
+const toast = useToast();
+toast.success("Boleto salvo", "Fulano de Tal · R$ 1.234,56");
+toast.error("Não foi possível salvar");
+```
+
 - **Fonts:** `styles.css` loads Raleway and JetBrains Mono from Google Fonts. To self-host them, import `tokens.css` and your own font files instead.
 
 ## What's inside
@@ -36,6 +64,7 @@ export function Toolbar() {
 | Export | Contents |
 | --- | --- |
 | `@hemerson/design-system` | React components |
+| `@hemerson/design-system/appearance` | `applyStoredAppearance()`, `setTheme()`, `setTransparency()`, without React |
 | `@hemerson/design-system/glass` | `enableGlassRefraction()`, the Chromium edge lens, without React |
 | `@hemerson/design-system/styles.css` | Fonts, tokens and component styles |
 | `@hemerson/design-system/tokens.css` | CSS custom properties for both themes |

package/dist/appearance/appearance.d.ts

@@ -0,0 +1,23 @@
+export type Theme = "dark" | "light";
+export type Transparency = "full" | "reduced";
+export interface Appearance {
+    theme: Theme;
+    transparency: Transparency;
+}
+export declare const APPEARANCE_STORAGE_KEYS: {
+    readonly theme: "hds-theme";
+    readonly transparency: "hds-transparency";
+};
+/** The saved choices, or dark with full transparency when nothing is saved. */
+export declare function readStoredAppearance(): Appearance;
+/** What <html> currently shows. */
+export declare function getAppearance(): Appearance;
+/**
+ * Puts the saved theme and transparency on <html>, dark when nothing is saved.
+ * Call it as early as possible, before the first paint, so the page never flashes the other theme.
+ */
+export declare function applyStoredAppearance(): Appearance;
+export declare function setTheme(theme: Theme): void;
+export declare function setTransparency(transparency: Transparency): void;
+/** Runs `listener` whenever the theme or transparency changes through these helpers. */
+export declare function subscribeToAppearance(listener: () => void): () => void;

package/dist/appearance/index.d.ts

@@ -0,0 +1,2 @@
+export { APPEARANCE_STORAGE_KEYS, applyStoredAppearance, getAppearance, readStoredAppearance, setTheme, setTransparency, subscribeToAppearance, } from "./appearance";
+export type { Appearance, Theme, Transparency } from "./appearance";

package/dist/appearance/useAppearance.d.ts

@@ -0,0 +1,13 @@
+import { type Appearance, type Theme, type Transparency } from "./appearance";
+export interface UseAppearance extends Appearance {
+    setTheme: (theme: Theme) => void;
+    setTransparency: (transparency: Transparency) => void;
+    toggleTheme: () => void;
+    toggleTransparency: () => void;
+}
+/**
+ * The page's theme and transparency, kept in sync across every component that uses it.
+ * The first use applies the saved choice (dark when nothing is saved), unless the app already
+ * called applyStoredAppearance() at startup.
+ */
+export declare function useAppearance(): UseAppearance;

package/dist/appearance-J15aUjQp.js

@@ -0,0 +1,57 @@
+//#region src/appearance/appearance.ts
+var e = {
+	theme: "hds-theme",
+	transparency: "hds-transparency"
+}, t = /* @__PURE__ */ new Set();
+function n(e) {
+	try {
+		return localStorage.getItem(e);
+	} catch {
+		return null;
+	}
+}
+function r(e, t) {
+	try {
+		localStorage.setItem(e, t);
+	} catch {}
+}
+function i() {
+	return {
+		theme: n(e.theme) === "light" ? "light" : "dark",
+		transparency: n(e.transparency) === "reduced" ? "reduced" : "full"
+	};
+}
+function a() {
+	let e = document.documentElement;
+	return {
+		theme: e.getAttribute("data-theme") === "light" ? "light" : "dark",
+		transparency: e.getAttribute("data-transparency") === "reduced" ? "reduced" : "full"
+	};
+}
+function o({ theme: e, transparency: n }) {
+	let r = document.documentElement;
+	r.setAttribute("data-theme", e), n === "reduced" ? r.setAttribute("data-transparency", "reduced") : r.removeAttribute("data-transparency"), t.forEach((e) => e());
+}
+function s() {
+	let e = i();
+	return o(e), e;
+}
+function c(t) {
+	r(e.theme, t), o({
+		...a(),
+		theme: t
+	});
+}
+function l(t) {
+	r(e.transparency, t), o({
+		...a(),
+		transparency: t
+	});
+}
+function u(e) {
+	return t.add(e), () => t.delete(e);
+}
+//#endregion
+export { c as a, i, s as n, l as o, a as r, u as s, e as t };
+
+//# sourceMappingURL=appearance-J15aUjQp.js.map

package/dist/appearance-J15aUjQp.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"appearance-J15aUjQp.js","names":["APPEARANCE_STORAGE_KEYS","listeners","read","key","write","value","readStoredAppearance","getAppearance","root","apply","theme","transparency","listener","applyStoredAppearance","appearance","setTheme","setTransparency","subscribeToAppearance"],"sources":["../src/appearance/appearance.ts"],"sourcesContent":["/*\n * Theme and transparency for the whole page, kept on <html> and remembered in localStorage.\n * Projects open in the dark theme whatever the system setting: light, and reduced\n * transparency, are the visitor's own choices. No React here, so plain HTML pages can use it.\n */\n\nexport type Theme = \"dark\" | \"light\";\nexport type Transparency = \"full\" | \"reduced\";\n\nexport interface Appearance {\n  theme: Theme;\n  transparency: Transparency;\n}\n\nexport const APPEARANCE_STORAGE_KEYS = {\n  theme: \"hds-theme\",\n  transparency: \"hds-transparency\",\n} as const;\n\nconst listeners = new Set<() => void>();\n\nfunction read(key: string): string | null {\n  try {\n    return localStorage.getItem(key);\n  } catch {\n    // Private windows and blocked storage: fall back to the defaults\n    return null;\n  }\n}\n\nfunction write(key: string, value: string) {\n  try {\n    localStorage.setItem(key, value);\n  } catch {\n    // The choice still applies for this visit\n  }\n}\n\n/** The saved choices, or dark with full transparency when nothing is saved. */\nexport function readStoredAppearance(): Appearance {\n  return {\n    theme: read(APPEARANCE_STORAGE_KEYS.theme) === \"light\" ? \"light\" : \"dark\",\n    transparency: read(APPEARANCE_STORAGE_KEYS.transparency) === \"reduced\" ? \"reduced\" : \"full\",\n  };\n}\n\n/** What <html> currently shows. */\nexport function getAppearance(): Appearance {\n  const root = document.documentElement;\n  return {\n    theme: root.getAttribute(\"data-theme\") === \"light\" ? \"light\" : \"dark\",\n    transparency: root.getAttribute(\"data-transparency\") === \"reduced\" ? \"reduced\" : \"full\",\n  };\n}\n\nfunction apply({ theme, transparency }: Appearance) {\n  const root = document.documentElement;\n  root.setAttribute(\"data-theme\", theme);\n  if (transparency === \"reduced\") {\n    root.setAttribute(\"data-transparency\", \"reduced\");\n  } else {\n    root.removeAttribute(\"data-transparency\");\n  }\n  listeners.forEach((listener) => listener());\n}\n\n/**\n * Puts the saved theme and transparency on <html>, dark when nothing is saved.\n * Call it as early as possible, before the first paint, so the page never flashes the other theme.\n */\nexport function applyStoredAppearance(): Appearance {\n  const appearance = readStoredAppearance();\n  apply(appearance);\n  return appearance;\n}\n\nexport function setTheme(theme: Theme) {\n  write(APPEARANCE_STORAGE_KEYS.theme, theme);\n  apply({ ...getAppearance(), theme });\n}\n\nexport function setTransparency(transparency: Transparency) {\n  write(APPEARANCE_STORAGE_KEYS.transparency, transparency);\n  apply({ ...getAppearance(), transparency });\n}\n\n/** Runs `listener` whenever the theme or transparency changes through these helpers. */\nexport function subscribeToAppearance(listener: () => void): () => void {\n  listeners.add(listener);\n  return () => listeners.delete(listener);\n}\n"],"mappings":";AAcA,IAAaA,IAA0B;CACrC,OAAO;CACP,cAAc;AAChB,GAEMC,oBAAY,IAAI,IAAgB;AAEtC,SAASC,EAAK,GAA4B;CACxC,IAAI;EACF,OAAO,aAAa,QAAQC,CAAG;CACjC,QAAQ;EAEN,OAAO;CACT;AACF;AAEA,SAASC,EAAM,GAAa,GAAe;CACzC,IAAI;EACF,aAAa,QAAQD,GAAKE,CAAK;CACjC,QAAQ,CAER;AACF;AAGA,SAAgBC,IAAmC;CACjD,OAAO;EACL,OAAOJ,EAAKF,EAAwB,KAAK,MAAM,UAAU,UAAU;EACnE,cAAcE,EAAKF,EAAwB,YAAY,MAAM,YAAY,YAAY;CACvF;AACF;AAGA,SAAgBO,IAA4B;CAC1C,IAAMC,IAAO,SAAS;CACtB,OAAO;EACL,OAAOA,EAAK,aAAa,YAAY,MAAM,UAAU,UAAU;EAC/D,cAAcA,EAAK,aAAa,mBAAmB,MAAM,YAAY,YAAY;CACnF;AACF;AAEA,SAASC,EAAM,EAAE,UAAO,mBAA4B;CAClD,IAAMD,IAAO,SAAS;CAOtB,AANAA,EAAK,aAAa,cAAcE,CAAK,GACjCC,MAAiB,YACnBH,EAAK,aAAa,qBAAqB,SAAS,IAEhDA,EAAK,gBAAgB,mBAAmB,GAE1CP,EAAU,SAAS,MAAaW,EAAS,CAAC;AAC5C;AAMA,SAAgBC,IAAoC;CAClD,IAAMC,IAAaR,EAAqB;CAExC,OADAG,EAAMK,CAAU,GACTA;AACT;AAEA,SAAgBC,EAAS,GAAc;CAErC,AADAX,EAAMJ,EAAwB,OAAOU,CAAK,GAC1CD,EAAM;EAAE,GAAGF,EAAc;EAAG;CAAM,CAAC;AACrC;AAEA,SAAgBS,EAAgB,GAA4B;CAE1D,AADAZ,EAAMJ,EAAwB,cAAcW,CAAY,GACxDF,EAAM;EAAE,GAAGF,EAAc;EAAG;CAAa,CAAC;AAC5C;AAGA,SAAgBU,EAAsB,GAAkC;CAEtE,OADAhB,EAAU,IAAIW,CAAQ,SACTX,EAAU,OAAOW,CAAQ;AACxC"}

package/dist/appearance.js

@@ -0,0 +1 @@
+export { t as APPEARANCE_STORAGE_KEYS, n as applyStoredAppearance, r as getAppearance, i as readStoredAppearance, a as setTheme, o as setTransparency, s as subscribeToAppearance } from "./appearance-J15aUjQp.js";

package/dist/components/AppearanceToggles/AppearanceToggles.d.ts

@@ -0,0 +1,17 @@
+import { type ButtonProps } from "../Button/Button";
+type ToggleProps = Omit<ButtonProps, "onClick" | "children" | "icon" | "iconOnly" | "aria-label" | "aria-pressed">;
+export interface ThemeToggleProps extends ToggleProps {
+    /** Accessible name while dark. Default "Mudar para o tema claro". */
+    lightLabel?: string;
+    /** Accessible name while light. Default "Mudar para o tema escuro". */
+    darkLabel?: string;
+}
+/** Switches between the dark theme (the default) and the light one, and remembers the choice. */
+export declare function ThemeToggle({ lightLabel, darkLabel, variant, ...rest }: ThemeToggleProps): import("react").JSX.Element;
+export interface TransparencyToggleProps extends ToggleProps {
+    /** Accessible name. Default "Reduzir transparência"; the pressed state says whether it is on. */
+    label?: string;
+}
+/** Turns every glass surface solid, or back to glass, and remembers the choice. */
+export declare function TransparencyToggle({ label, variant, ...rest }: TransparencyToggleProps): import("react").JSX.Element;
+export {};

package/dist/components/Dialog/Dialog.d.ts

@@ -12,7 +12,9 @@ export interface DialogProps {
     closeLabel?: string;
     /** `panel` focuses the panel itself instead of its first control. */
     initialFocus?: "first" | "panel";
+    /** md (default, 560px) for forms and confirmations · lg (880px) for wide content such as a print preview. */
+    size?: "md" | "lg";
     className?: string;
 }
 /** A modal panel of thick glass for a focused task or a confirmation. */
-export declare function Dialog({ open, onClose, title, description, children, footer, closeLabel, initialFocus, className, }: DialogProps): import("react").ReactPortal | null;
+export declare function Dialog({ open, onClose, title, description, children, footer, closeLabel, initialFocus, size, className, }: DialogProps): import("react").ReactPortal | null;

package/dist/components/Toast/Toast.d.ts

@@ -1,5 +1,6 @@
-import { type ReactNode } from "react";
-export type ToastTone = "neutral" | "success" | "warning" | "danger";
+import type { ReactNode } from "react";
+import { type ToastTone } from "./ToastView";
+export type { ToastTone } from "./ToastView";
 export interface ToastProps {
     open: boolean;
     onClose?: () => void;
@@ -12,5 +13,8 @@ export interface ToastProps {
     closeLabel?: string;
     className?: string;
 }
-/** A short glass notice at the bottom of the screen that confirms an action or reports a problem. */
+/**
+ * A short glass notice at the bottom of the screen that confirms an action or reports a problem.
+ * To raise toasts from anywhere in an app, wrap it in ToastProvider and use `useToast()` instead.
+ */
 export declare function Toast({ open, onClose, tone, title, description, duration, closeLabel, className, }: ToastProps): import("react").ReactPortal | null;

package/dist/components/Toast/ToastProvider.d.ts

@@ -0,0 +1,29 @@
+import { type ReactNode } from "react";
+import { type ToastTone } from "./ToastView";
+export interface ToastOptions {
+    title: ReactNode;
+    description?: ReactNode;
+    tone?: ToastTone;
+    /** Milliseconds before it closes itself; 0 keeps it open until dismissed. Default 5000. */
+    duration?: number;
+}
+export interface ToastApi {
+    /** Shows a toast and returns its id, for `dismiss`. */
+    show: (options: ToastOptions) => string;
+    success: (title: ReactNode, description?: ReactNode) => string;
+    error: (title: ReactNode, description?: ReactNode) => string;
+    warning: (title: ReactNode, description?: ReactNode) => string;
+    info: (title: ReactNode, description?: ReactNode) => string;
+    dismiss: (id: string) => void;
+}
+export interface ToastProviderProps {
+    children?: ReactNode;
+    /** Most toasts shown at once; the oldest goes first. Default 3. */
+    max?: number;
+    /** Accessible name of each close button. Default "Fechar aviso". */
+    closeLabel?: string;
+}
+/** Shows the toasts raised with `useToast()` anywhere inside it, stacked at the bottom of the screen. */
+export declare function ToastProvider({ children, max, closeLabel }: ToastProviderProps): import("react").JSX.Element;
+/** Raises toasts from anywhere inside a ToastProvider: `toast.success("Boleto salvo")`. */
+export declare function useToast(): ToastApi;

package/dist/components/Toast/ToastView.d.ts

@@ -0,0 +1,14 @@
+import { type ReactNode } from "react";
+export type ToastTone = "neutral" | "success" | "warning" | "danger";
+export interface ToastViewProps {
+    tone: ToastTone;
+    title: ReactNode;
+    description?: ReactNode;
+    /** Milliseconds before it closes itself; 0 keeps it open. */
+    duration: number;
+    onClose?: () => void;
+    closeLabel: string;
+    className?: string;
+}
+/** One toast: the glass card, its icon and close button, and a timer that pauses on hover or focus. */
+export declare function ToastView({ tone, title, description, duration, onClose, closeLabel, className }: ToastViewProps): import("react").JSX.Element;

package/dist/index.d.ts

@@ -16,6 +16,8 @@ export { Dialog } from "./components/Dialog/Dialog";
 export type { DialogProps } from "./components/Dialog/Dialog";
 export { Toast } from "./components/Toast/Toast";
 export type { ToastProps, ToastTone } from "./components/Toast/Toast";
+export { ToastProvider, useToast } from "./components/Toast/ToastProvider";
+export type { ToastApi, ToastOptions, ToastProviderProps } from "./components/Toast/ToastProvider";
 export { Input } from "./components/Input/Input";
 export type { InputProps } from "./components/Input/Input";
 export { Select } from "./components/Select/Select";
@@ -28,6 +30,11 @@ export { Badge } from "./components/Badge/Badge";
 export type { BadgeProps, BadgeTone } from "./components/Badge/Badge";
 export { Table } from "./components/Table/Table";
 export type { TableColumn, TableProps } from "./components/Table/Table";
+export { ThemeToggle, TransparencyToggle } from "./components/AppearanceToggles/AppearanceToggles";
+export type { ThemeToggleProps, TransparencyToggleProps } from "./components/AppearanceToggles/AppearanceToggles";
+export { useAppearance } from "./appearance/useAppearance";
+export type { UseAppearance } from "./appearance/useAppearance";
+export * from "./appearance/index";
 export { Container } from "./components/Container/Container";
 export type { ContainerProps } from "./components/Container/Container";
 export { SectionTitle } from "./components/SectionTitle/SectionTitle";