@dataimago/ui 0.1.0-alpha.3 → 0.1.0-alpha.34

package/dist/index.d.ts

@@ -1,5 +1,6 @@
 import * as React from 'react';
 import * as react_jsx_runtime from 'react/jsx-runtime';
+import { LogoId, LogoVariant, AnimationId, NavbarLogoId } from '@dataimago/brand';
 
 type ButtonVariant = 'primary' | 'secondary' | 'ghost';
 type ButtonSize = 'sm' | 'md' | 'lg';
@@ -49,8 +50,8 @@ declare function LogoMonogram({ size, title, ...rest }: LogoMonogramProps): reac
 
 /**
  * <LogoMonogramBg /> — the dataimago 'a + i' monogram with a rounded accent
- * backplate. White letters on the historical brand-red role
- * (var(--color-interactive-accent), the emancipation copper-red).
+ * backplate. White letters on the brand-accent role
+ * (var(--color-interactive-accent), iteration-2 sky-blue).
  *
  * Use this variant on neutral surfaces where the no-background monogram
  * would lack presence — favicons, app icons, social-media avatars, or any
@@ -60,10 +61,16 @@ declare function LogoMonogram({ size, title, ...rest }: LogoMonogramProps): reac
  * FOUNDATIONS/background/04_dataimago_Content/Design_Assets/logos/
  *   ai_monogram_supreme_bg_1_PATH.svg
  *
- * Theming: the background uses var(--color-interactive-accent), so the mark
- * picks up the canonical accent color in both light and dark modes. The
- * letter fill is hard-set to white because the accent backplate is dark
- * enough that white letters always have AAA contrast (verified in iteration-1).
+ * Theming: the background uses var(--color-interactive-accent), which
+ * resolves via theme-colors.json's mode-aware role mapping — accent-500
+ * (#1f618d) on light surfaces, accent-300 (#3498DB) on dark. The letter
+ * fill is hard-set to white; both accent stops have AA-or-better contrast
+ * with white letters (light-mode 6.66:1 AA, dark-mode 3.15:1 AA-large for
+ * the dot-and-stem heading-size letters used in the monogram). The
+ * literal-fallback in this component is light-mode (#1f618d, sky-blue
+ * iteration-2) for rare non-CSS-aware contexts. Iteration-1's copper-red
+ * fallback (#b54a27) was retired in iteration-2-B.2; see
+ * wiki/decisions/iteration-2-blue-accent.md for the rationale.
  *
  * Usage:
  *   <LogoMonogramBg size={64} aria-label="dataimago" />
@@ -78,8 +85,8 @@ declare function LogoMonogramBg({ size, title, ...rest }: LogoMonogramBgProps):
 
 /**
  * <LogoWordmark /> — the full "dataimago" wordmark with the 'ai' overlap.
- * White letters on a rounded accent backplate (the historical brand-red role,
- * var(--color-interactive-accent)).
+ * White letters on a rounded accent backplate, themed via
+ * var(--color-interactive-accent).
  *
  * Use this variant for primary brand surfaces: site headers, document
  * letterheads, large-format presentations, business materials. For compact
@@ -95,6 +102,15 @@ declare function LogoMonogramBg({ size, title, ...rest }: LogoMonogramBgProps):
  * FOUNDATIONS/background/04_dataimago_Content/Design_Assets/logos/
  *   dataimago_supreme_1_PATH.svg
  *
+ * Theming: the backplate uses var(--color-interactive-accent), which resolves
+ * via theme-colors.json's mode-aware role mapping — accent-500 (#1f618d) on
+ * light surfaces, accent-300 (#3498DB) on dark. The literal-fallback in this
+ * component is light-mode (#1f618d, sky-blue iteration-2) for the rare cases
+ * where the SVG is consumed without CSS-variable resolution (printed PDFs from
+ * raw SVG, third-party platforms that strip CSS). Iteration-1's copper-red
+ * fallback (#b54a27) was retired in iteration-2-B.2; see
+ * wiki/decisions/iteration-2-blue-accent.md for the rationale.
+ *
  * Usage:
  *   <LogoWordmark width={240} aria-label="dataimago" />
  *
@@ -109,4 +125,222 @@ interface LogoWordmarkProps extends React.SVGAttributes<SVGSVGElement> {
 }
 declare function LogoWordmark({ width, title, ...rest }: LogoWordmarkProps): react_jsx_runtime.JSX.Element;
 
-export { Button, type ButtonProps, type ButtonSize, type ButtonVariant, LogoMonogram, LogoMonogramBg, type LogoMonogramBgProps, type LogoMonogramProps, LogoWordmark, type LogoWordmarkProps };
+interface LogoProps extends React.HTMLAttributes<HTMLSpanElement> {
+    /** Mark id, e.g. `dissertation_ai_OVERLAP`. */
+    name: LogoId;
+    /** PATH (default), CUTOUT, BG, or LETTERS. See @dataimago/brand. */
+    variant?: LogoVariant;
+    /**
+     * Render width (px number or any CSS length). Height scales proportionally
+     * via the SVG viewBox. Omit to use the mark's intrinsic size.
+     */
+    width?: number | string;
+}
+/**
+ * Manifest-driven brand mark from `@dataimago/brand`. Inlines the SVG string so
+ * `currentColor` (PATH/LETTERS), the `--color-interactive-accent` badge fill
+ * (CUTOUT/BG), and the per-letter interaction classes (`.glyph`, `.logo-*`) all
+ * work — an `<img src>` can't receive those interior styles.
+ *
+ * Color flows from CSS: set `color` (PATH/LETTERS) on this element or an
+ * ancestor. Size via `width` (or CSS on the wrapper).
+ */
+declare function Logo({ name, variant, width, style, ...rest }: LogoProps): react_jsx_runtime.JSX.Element | null;
+
+/** A link the lockup renders; pass one to route through a framework link (e.g. next/link). */
+interface CopulaLinkProps {
+    href: string;
+    'aria-label': string;
+    className?: string;
+    style?: React.CSSProperties;
+    children: React.ReactNode;
+}
+interface CopulaLockupProps extends React.HTMLAttributes<HTMLSpanElement> {
+    /** The property's wordmark id, e.g. `dissertation_ai`. Its PATH variant is drawn. */
+    property: LogoId;
+    /** Accessible name of the property link, e.g. `dissertation-ai`. */
+    propertyLabel: string;
+    /** Where the property mark links. Defaults to `/`. */
+    propertyHref?: string;
+    /**
+     * `shown` (default): "<property> is dataimago". `hidden`: the property mark
+     * alone, with no badge, no dataimago wordmark and no link to dataimago, for
+     * apps that keep dataimago out of view while it is in stealth.
+     */
+    dataimago?: 'shown' | 'hidden';
+    /** Where the dataimago wordmark links. Defaults to https://dataimago.ai. */
+    brandHref?: string;
+    /** Wordmark height in px. Defaults to 32; the badge and spacing scale with it. */
+    height?: number;
+    /** Class for each link (colour and hover); both links share one treatment. */
+    linkClassName?: string;
+    /** Render the links with a framework component. Defaults to a plain `<a>`. */
+    renderLink?: (props: CopulaLinkProps) => React.ReactNode;
+}
+/**
+ * The copula lockup, "dissertation-ai **is** dataimago": the property wordmark,
+ * the `is_badge` disc and the dataimago wordmark, each wordmark its own link
+ * (wiki/connections/is-copula-coupling.md). The badge is a mark, not a link: at
+ * 16px it is below the 24px pointer-target floor (WCAG 2.5.8), so it is read as
+ * "is" and the philosophy page stays reachable from the nav.
+ *
+ * Spacing is ink-symmetric about the badge centre, computed from each mark's
+ * `ink` box in the @dataimago/brand manifest, so any property mark lines up
+ * without hand-tuned margins. Geometry is inline style (no Tailwind), so a
+ * consumer on plain CSS can use it too. Colour is `currentColor`: set `color`.
+ */
+declare function CopulaLockup({ property, propertyLabel, propertyHref, dataimago, brandHref, height, linkClassName, renderLink, style, ...rest }: CopulaLockupProps): react_jsx_runtime.JSX.Element | null;
+
+interface BrandAnimationProps extends React.HTMLAttributes<HTMLSpanElement> {
+    /** Animation id, e.g. `dissertation-ai`. See @dataimago/brand animations.json. */
+    name: AnimationId;
+    /**
+     * Render width (px number or any CSS length). Height scales via the SVG
+     * viewBox. Omit to use the animation's intrinsic size.
+     */
+    width?: number | string;
+}
+/**
+ * Decorative brand animation from `@dataimago/brand` (the animation-foundry).
+ * Inlines the pure-SMIL SVG string so its interior `<style>` works — an
+ * `<img src>` can't receive those styles (same rationale as `<Logo>`).
+ *
+ * Motion-dignity: decorative brand animation is a distinct category from the
+ * 300ms UI-transition ceiling, but it is contractually gated on
+ * `prefers-reduced-motion`. When the user prefers reduced motion this renders
+ * the static brand mark the animation settles to (its `poster`) via `<Logo>`,
+ * so no consumer can ship the motion without the fallback.
+ */
+declare function BrandAnimation({ name, width, style, ...rest }: BrandAnimationProps): react_jsx_runtime.JSX.Element | null;
+
+interface NavbarLogoProps extends React.HTMLAttributes<HTMLSpanElement> {
+    /** Navbar mark id, e.g. `dissertation-ai`. See @dataimago/brand navbar.json. */
+    name: NavbarLogoId;
+    /**
+     * Render width (px number or any CSS length). Height scales via the SVG
+     * viewBox. Omit to use the mark's intrinsic size.
+     */
+    width?: number | string;
+}
+/**
+ * Animated brand mark for an app navbar, from `@dataimago/brand` (the
+ * animation-foundry's navbar set). Inlines the self-contained CSS-animated SVG
+ * so its interior `<style>` works — an `<img src>` can't receive those styles.
+ *
+ * Behaviour by mark kind (from the navbar manifest):
+ *   - `assemble` (L2: dissertation-ai, rpkg-ai, SGPc-ai): the trailing `a`/`i`
+ *     start apart and the `i` slides onto the `a`. Plays once on mount; replays
+ *     on pointer-enter via a remount (`replayKey`).
+ *   - `shimmer` (L1: dataimago-ai): the monogram is always superimposed; an
+ *     accent shimmer sweeps on `:hover` from the SVG's own CSS (no JS trigger).
+ *   - `dream` (promoted dream marks, `tools/dream-foundry/drop.mjs promote`):
+ *     a self-contained CSS hover gesture like liftwash; the poster is the mark's
+ *     own static form (`dream_<slug>` / `DREAM`). Ink is `currentColor`.
+ *
+ * Motion-dignity: the embedded CSS animation is <= 300ms and gated on
+ * `@media (prefers-reduced-motion: no-preference)`. When the user prefers
+ * reduced motion this renders the static settled mark (the manifest `poster`,
+ * the superimposed monogram) via `<Logo>` — so no consumer can ship the motion
+ * without the fallback.
+ */
+declare function NavbarLogo({ name, width, style, ...rest }: NavbarLogoProps): react_jsx_runtime.JSX.Element | null;
+
+/**
+ * Light/dark theme preference for dataimago apps.
+ *
+ * The house tokens (`@dataimago/tokens`) follow the operating system through
+ * `prefers-color-scheme` and yield to an explicit `data-bs-theme` on the root:
+ * `light` or `dark` forces that theme, no attribute means "follow the system".
+ * This module owns that attribute: it reads and stores the reader's choice,
+ * applies it, and reports the theme actually in effect (for canvas and WebGL
+ * surfaces that cannot read CSS variables).
+ *
+ * The choice is a per-browser convenience in localStorage. Every read and write
+ * is guarded: in a private window or with storage blocked the page simply
+ * follows the system.
+ */
+type ThemePreference = 'system' | 'light' | 'dark';
+type ResolvedTheme = 'light' | 'dark';
+declare const THEME_STORAGE_KEY = "dataimago-theme";
+declare const THEME_ATTRIBUTE = "data-bs-theme";
+/**
+ * Inline this in `<head>` before any stylesheet paints, so a stored choice is
+ * on the root before first paint (no flash of the other theme). The server
+ * markup cannot know the choice, so the consumer also puts
+ * `suppressHydrationWarning` on `<html>`. From a React server layout, render
+ * `<ThemeScript />` instead: this package is a client bundle, so a server
+ * component cannot import the string itself.
+ *
+ * ```tsx
+ * <html lang="en" suppressHydrationWarning>
+ *   <head><ThemeScript /></head>
+ * ```
+ */
+declare const themeInitScript: string;
+/** The stored choice, or `'system'` when there is none (or storage is unavailable). */
+declare function readThemePreference(): ThemePreference;
+/** Store, apply and announce a choice. `'system'` clears the stored choice. */
+declare function setThemePreference(preference: ThemePreference): void;
+/** The theme in effect: the root attribute when set, otherwise the system's. */
+declare function resolveTheme(): ResolvedTheme;
+/**
+ * The reader's choice and a setter. Server render and hydration see
+ * `'system'`; the stored choice arrives right after.
+ */
+declare function useThemePreference(): [ThemePreference, (p: ThemePreference) => void];
+/**
+ * The theme in effect, for surfaces that cannot read CSS variables (canvas,
+ * WebGL maps). Follows the toggle and, under "system", the operating system.
+ * Server render and hydration see `'light'`.
+ */
+declare function useResolvedTheme(): ResolvedTheme;
+
+interface ThemeToggleLabels {
+    /** What the control sets, read before the theme in effect ("Theme: Light"). */
+    name: string;
+    /** Added when the theme follows the operating system ("Theme: Light (System)"). */
+    system: string;
+    light: string;
+    dark: string;
+}
+interface ThemeToggleProps extends Omit<React.ButtonHTMLAttributes<HTMLButtonElement>, 'onClick' | 'children' | 'type'> {
+    /** Accessible and tooltip text; pass the property's own wording. */
+    labels?: Partial<ThemeToggleLabels>;
+}
+/**
+ * The choice one click makes: the other theme, stored as "system" when that is
+ * the operating system's own, so the page goes back to following it.
+ */
+declare function nextThemePreference(shown: ResolvedTheme, system: ResolvedTheme): ThemePreference;
+/**
+ * Light/dark toggle for an app navbar: one button, and one click always flips
+ * the theme on screen. The page follows the operating system until the first
+ * click; a click that lands on the system's own theme goes back to following
+ * it (no stored choice), and the other theme is stored and set as
+ * `data-bs-theme` on the root, which the house tokens obey. The icon shows the
+ * theme in effect: a sun in light, a moon in dark.
+ *
+ * A 48px target (the dataimago touch floor). The icon is `currentColor`.
+ * Inline styles would beat a consumer's `:hover` rule, so the two colours a
+ * navbar restyles read custom properties instead: set `--di-theme-toggle-fg`
+ * and `--di-theme-toggle-bg` on `.di-ui-theme-toggle` (and its `:hover`).
+ * Pair it with `<ThemeScript />` in `<head>` so a stored choice applies before
+ * first paint.
+ */
+declare function ThemeToggle({ labels, className, style, ...rest }: ThemeToggleProps): react_jsx_runtime.JSX.Element;
+
+interface ThemeScriptProps {
+    /** Content-Security-Policy nonce, when the app sets one. */
+    nonce?: string;
+}
+/**
+ * Renders `themeInitScript` as an inline `<script>`, so a stored choice is on
+ * the root before first paint. Use this from a server layout: this package is
+ * a client bundle, so a server component cannot import the plain string, but
+ * it can render this component. Put it in `<head>` and add
+ * `suppressHydrationWarning` to `<html>` (the script changes its attributes
+ * before React hydrates).
+ */
+declare function ThemeScript({ nonce }: ThemeScriptProps): react_jsx_runtime.JSX.Element;
+
+export { BrandAnimation, type BrandAnimationProps, Button, type ButtonProps, type ButtonSize, type ButtonVariant, type CopulaLinkProps, CopulaLockup, type CopulaLockupProps, Logo, LogoMonogram, LogoMonogramBg, type LogoMonogramBgProps, type LogoMonogramProps, type LogoProps, LogoWordmark, type LogoWordmarkProps, NavbarLogo, type NavbarLogoProps, type ResolvedTheme, THEME_ATTRIBUTE, THEME_STORAGE_KEY, type ThemePreference, ThemeScript, type ThemeScriptProps, ThemeToggle, type ThemeToggleLabels, type ThemeToggleProps, nextThemePreference, readThemePreference, resolveTheme, setThemePreference, themeInitScript, useResolvedTheme, useThemePreference };