foss-design 0.2.0 → 0.3.0

package/dist/viewer-lib/types/src/shared/devices.d.ts

@@ -0,0 +1,46 @@
+/** Frame presets, in CSS pixels. */
+export declare const DEVICES: {
+    readonly phone: {
+        readonly width: 390;
+        readonly height: 844;
+        readonly label: 'Phone';
+    };
+    readonly 'phone-sm': {
+        readonly width: 375;
+        readonly height: 667;
+        readonly label: 'Phone S';
+    };
+    readonly 'phone-lg': {
+        readonly width: 430;
+        readonly height: 932;
+        readonly label: 'Phone L';
+    };
+    readonly tablet: {
+        readonly width: 834;
+        readonly height: 1194;
+        readonly label: 'Tablet';
+    };
+    readonly 'tablet-landscape': {
+        readonly width: 1194;
+        readonly height: 834;
+        readonly label: 'Tablet landscape';
+    };
+    readonly laptop: {
+        readonly width: 1280;
+        readonly height: 800;
+        readonly label: 'Laptop';
+    };
+    readonly desktop: {
+        readonly width: 1440;
+        readonly height: 900;
+        readonly label: 'Desktop';
+    };
+    readonly wide: {
+        readonly width: 1920;
+        readonly height: 1080;
+        readonly label: 'Wide';
+    };
+};
+export type DeviceName = keyof typeof DEVICES;
+export declare const DEVICE_NAMES: [DeviceName, ...DeviceName[]];
+export declare const DEFAULT_DEVICE: DeviceName;

package/dist/viewer-lib/types/src/shared/types.d.ts

@@ -0,0 +1,355 @@
+/** Contracts shared by the server, the static build and the viewer. */
+export type Theme = 'light' | 'dark';
+export interface Issue {
+    severity: 'error' | 'warning';
+    /** Path relative to the project root. */
+    file: string;
+    message: string;
+    /** Where in the file, such as `pages[0].sections[1].items[2].src`. */
+    at?: string;
+}
+export interface ProjectInfo {
+    name: string;
+    root: string;
+    /** True in a static build: no live reload, no snapshots, hash routing. */
+    static: boolean;
+    version: string;
+    system: SystemSummary | null;
+    canvases: CanvasSummary[];
+    issues: Issue[];
+}
+export interface SystemSummary {
+    name: string;
+    description?: string;
+    tokens: number;
+    components: number;
+    guidelines: number;
+    issues: number;
+}
+export interface CanvasSummary {
+    id: string;
+    title: string;
+    description?: string;
+    pages: number;
+    screens: number;
+    updatedAt: number;
+    issues: number;
+    /** A snapshot of the first screen, for the canvas card. */
+    cover?: string;
+}
+export interface FrameSize {
+    width: number;
+    /** `auto` grows the frame to the screen's content. */
+    height: number | 'auto';
+    device?: string;
+}
+interface ItemBase {
+    id: string;
+    title: string;
+    description?: string;
+    /** Free-layout position on the page, in canvas pixels. */
+    x?: number;
+    y?: number;
+}
+export interface ScreenItem extends ItemBase {
+    kind: 'screen';
+    /** Source path relative to the canvas folder, as written in canvas.json. */
+    src: string;
+    /** Source path relative to the project root. */
+    file: string;
+    format: 'module' | 'html';
+    /** Frame URL without the theme parameter. */
+    url: string;
+    frame: FrameSize;
+    theme?: Theme;
+    missing?: boolean;
+    /** Changes when anything that needs a reload changes: props, theme, stylesheet. */
+    rev: string;
+    snapshots?: Partial<Record<Theme, string>>;
+    /** The snapshots shrunk to a few hundred pixels wide, for the zoomed-out canvas. */
+    thumbs?: Partial<Record<Theme, string>>;
+    /** Last content height the screen reported, for `auto` frames before they load. */
+    measuredHeight?: number;
+}
+export interface UrlItem extends ItemBase {
+    kind: 'url';
+    url: string;
+    frame: FrameSize;
+}
+export interface NoteItem extends ItemBase {
+    kind: 'note';
+    /** Markdown. */
+    text: string;
+    width: number;
+    tone: 'note' | 'plain';
+}
+export interface ImageItem extends ItemBase {
+    kind: 'image';
+    url: string;
+    width?: number;
+    missing?: boolean;
+}
+export type CanvasItem = ScreenItem | UrlItem | NoteItem | ImageItem;
+export interface CanvasSection {
+    id: string;
+    title?: string;
+    description?: string;
+    /** Wrap the row after this many items. */
+    columns?: number;
+    items: CanvasItem[];
+}
+export interface CanvasPage {
+    id: string;
+    title: string;
+    description?: string;
+    layout: 'sections' | 'free';
+    sections: CanvasSection[];
+}
+export interface CanvasDoc {
+    id: string;
+    title: string;
+    description?: string;
+    theme?: Theme;
+    pages: CanvasPage[];
+    issues: Issue[];
+    updatedAt: number;
+}
+export type TokenKind = 'color' | 'font' | 'text' | 'weight' | 'leading' | 'tracking' | 'spacing' | 'radius' | 'shadow' | 'blur' | 'ease' | 'animation' | 'duration' | 'breakpoint' | 'other';
+export interface TokenValue {
+    /** As written. */
+    raw: string;
+    /** With `var()` references substituted. */
+    value: string;
+}
+export interface Token {
+    /** The variable screens use, such as `--ink` or `--color-brand`. */
+    name: string;
+    kind: TokenKind;
+    group: string;
+    description?: string;
+    light?: TokenValue;
+    dark?: TokenValue;
+    /** Tailwind theme key, such as `ink` for `--color-ink` (bg-ink, text-ink). */
+    utility?: string;
+    /** Line height paired with a text size (`--text-sm--line-height`). */
+    lineHeight?: string;
+}
+export interface ComponentDoc {
+    id: string;
+    title: string;
+    group: string;
+    description?: string;
+    status?: string;
+    /** Specimen path relative to the project root. */
+    specimen: string;
+    /** Component source paths relative to the project root. */
+    sources: string[];
+    url: string;
+}
+export interface GuidelineDoc {
+    slug: string;
+    title: string;
+    order: number;
+    markdown: string;
+}
+export interface AssetDoc {
+    name: string;
+    /** Path relative to the system folder. */
+    path: string;
+    url: string;
+    size: number;
+    kind: 'image' | 'font' | 'other';
+}
+export interface SystemDoc {
+    name: string;
+    description?: string;
+    /** Stylesheet URLs (web fonts) the screens load. */
+    fonts: string[];
+    tokens: Token[];
+    components: ComponentDoc[];
+    guidelines: GuidelineDoc[];
+    assets: AssetDoc[];
+    /** Frame URL of the built-in typography specimen. */
+    typographyUrl: string | null;
+    issues: Issue[];
+}
+/** What the server pushes over /api/events. */
+export type DesignEvent = {
+    type: 'project';
+} | {
+    type: 'canvas';
+    id: string;
+} | {
+    type: 'system';
+} | {
+    type: 'snapshot';
+    canvas: string;
+    id: string;
+    theme: Theme;
+    url: string;
+    height?: number;
+};
+/** Top, right, bottom, left. */
+export type Box = [top: number, right: number, bottom: number, left: number];
+/** An element in an inspected frame; `ref` names it in messages back to the frame. */
+export interface Crumb {
+    ref: number;
+    label: string;
+}
+export interface ColorValue {
+    /** Readable: hex when the color is sRGB. */
+    value: string;
+    /** As computed, for painting a swatch. */
+    css: string;
+    token?: string;
+}
+/** What the inspector reports about the element picked in a frame. */
+export interface ElementInfo {
+    ref: number;
+    tag: string;
+    label: string;
+    text?: string;
+    classes: string[];
+    attributes: [string, string][];
+    component?: {
+        owners: string[];
+        file?: string;
+    };
+    rect: {
+        x: number;
+        y: number;
+        w: number;
+        h: number;
+    };
+    margin: Box;
+    border: Box;
+    padding: Box;
+    layout: [string, string][];
+    typography?: {
+        family: string;
+        familyToken?: string;
+        size: string;
+        sizeToken?: string;
+        weight: string;
+        lineHeight: string;
+        letterSpacing: string;
+        color: ColorValue;
+        align: string;
+        transform?: string;
+    };
+    appearance: {
+        background?: ColorValue;
+        backgroundImage?: string;
+        border?: {
+            width: string;
+            style: string;
+            color: ColorValue;
+        };
+        radius?: {
+            value: string;
+            token?: string;
+        };
+        shadow?: {
+            value: string;
+            token?: string;
+        };
+        opacity?: string;
+    };
+    path: Crumb[];
+    children: Crumb[];
+    /** The CSS worth copying, as a block. */
+    css: string;
+}
+/**
+ * Messages between the viewer and the runtime inside each frame. Frames may
+ * sit on another origin than the viewer, so everything goes through postMessage.
+ */
+export type RuntimeMessage = {
+    source: 'design-runtime';
+    key: string;
+    type: 'ready';
+} | {
+    source: 'design-runtime';
+    key: string;
+    type: 'size';
+    width: number;
+    height: number;
+} | {
+    source: 'design-runtime';
+    key: string;
+    type: 'error';
+    message: string;
+} | {
+    source: 'design-runtime';
+    key: string;
+    type: 'go';
+    target: string;
+} | {
+    source: 'design-runtime';
+    key: string;
+    type: 'wheel';
+    deltaX: number;
+    deltaY: number;
+    x: number;
+    y: number;
+    /** Pinch or ctrl/⌘-wheel: zoom the canvas; otherwise pan it. */
+    zoom: boolean;
+} | {
+    source: 'design-runtime';
+    key: string;
+    type: 'keydown';
+    code: string;
+}
+/** ⌘/Ctrl pressed or released in the frame, or a key pressed while one is down. */
+ | {
+    source: 'design-runtime';
+    key: string;
+    type: 'key';
+    name: string;
+    down: boolean;
+} | {
+    source: 'design-runtime';
+    key: string;
+    type: 'blur';
+} | {
+    source: 'design-runtime';
+    key: string;
+    type: 'updated';
+}
+/** The picked element changed, or its styles did; null when nothing is picked. */
+ | {
+    source: 'design-runtime';
+    key: string;
+    type: 'inspect';
+    info: ElementInfo | null;
+}
+/** Escape while inspecting with nothing picked. */
+ | {
+    source: 'design-runtime';
+    key: string;
+    type: 'inspect-escape';
+};
+export type ViewerMessage = {
+    source: 'design-viewer';
+    type: 'theme';
+    theme: Theme;
+}
+/** The frame is on the canvas: pan and zoom with the wheel go to the viewer. */
+ | {
+    source: 'design-viewer';
+    type: 'canvas';
+}
+/** Inspect mode on or off; `tokens` let the frame name the tokens behind computed styles. */
+ | {
+    source: 'design-viewer';
+    type: 'inspect';
+    on: boolean;
+    tokens?: Token[];
+}
+/** Pick an element by the `ref` a previous report gave it, or clear the pick without reporting. */
+ | {
+    source: 'design-viewer';
+    type: 'inspect-select';
+    ref: number | null;
+};
+export {};

package/dist/viewer-lib/types/viewer/src/app.d.ts

@@ -0,0 +1,20 @@
+import { type QueryClient } from '@tanstack/react-query';
+import type { ViewerSource } from './lib/source';
+import { type ViewerScope, type ViewerSlots } from './lib/viewer';
+export interface DesignViewerProps {
+    /** Where the project comes from: `localSource`, `staticSource` or the embedding app's own. Keep it stable. */
+    source: ViewerSource;
+    /**
+     * Path the viewer's routes live under, such as `/p/<projectId>`; it adds to the base of the
+     * wouter router around the viewer, whose location hook it also uses.
+     */
+    base?: string;
+    /** The `sandbox` attribute for every frame; none when unset. */
+    frameSandbox?: string;
+    slots?: ViewerSlots;
+    scope?: ViewerScope;
+    /** Shared with the embedding app; the viewer makes its own when unset. */
+    queryClient?: QueryClient;
+}
+/** The whole viewer: home, canvases, screens and the design system of one project. */
+export declare function DesignViewer({ source, base, frameSandbox, slots, scope, queryClient }: DesignViewerProps): import("react").JSX.Element;

package/dist/viewer-lib/types/viewer/src/components/auto-frame.d.ts

@@ -0,0 +1,13 @@
+import type { Theme } from '../../../src/shared/types';
+/**
+ * A frame that grows to its content: system specimens and the typography page.
+ * The theme is sent to the running frame; changing it does not reload it.
+ */
+export declare function AutoFrame({ src, theme, title, minHeight, width, className, }: {
+    src: string;
+    theme: Theme;
+    title: string;
+    minHeight?: number;
+    width?: number;
+    className?: string;
+}): import("react").JSX.Element;

package/dist/viewer-lib/types/viewer/src/components/code-view.d.ts

@@ -0,0 +1,6 @@
+/** Source with line numbers and syntax colors; the header carries the path and a copy button. */
+export declare function CodeView({ code, path, className }: {
+    code: string;
+    path?: string;
+    className?: string;
+}): import("react").JSX.Element;

package/dist/viewer-lib/types/viewer/src/components/command-palette.d.ts

@@ -0,0 +1,2 @@
+/** ⌘K: jump to canvases, pages, screens and system pages. */
+export declare function CommandPalette(): import("react").JSX.Element;

package/dist/viewer-lib/types/viewer/src/components/inspector.d.ts

@@ -0,0 +1,29 @@
+import type { ElementInfo } from '../../../src/shared/types';
+/**
+ * Inspect frames: while `enabled`, every frame in `frames` highlights on hover
+ * and picks on click. The inspecting runs inside each frame (see the runtime's
+ * inspect.ts); this side only switches it and shows what the frames report.
+ * The pick outlives `enabled` (so a quick ⌘-hold leaves the panel open) until
+ * it is cleared.
+ */
+export declare function useInspection(frames: HTMLIFrameElement[], enabled: boolean, options: {
+    onEscape(): void;
+}): {
+    info: ElementInfo | null;
+    frame: HTMLIFrameElement | null;
+    /** Pick another element in the same frame by its ref, or clear the pick. */
+    select(ref: number | null): void;
+};
+/**
+ * True while ⌘ or Ctrl is held on its own, in the viewer or inside any of
+ * `frames`. A modifier used for a shortcut (⌘K, ⌘C) does not count.
+ */
+export declare function useModifierHold(frames: HTMLIFrameElement[]): boolean;
+/** The right sidebar: what the selected element is and how it is styled. */
+export declare function InspectorPanel({ info, onSelect, onClose, active, }: {
+    info: ElementInfo | null;
+    onSelect(ref: number): void;
+    onClose(): void;
+    /** Whether a frame is being inspected right now. */
+    active: boolean;
+}): import("react").JSX.Element;

package/dist/viewer-lib/types/viewer/src/components/issues.d.ts

@@ -0,0 +1,10 @@
+import type { Issue } from '../../../src/shared/types';
+export declare function IssueList({ issues, className }: {
+    issues: Issue[];
+    className?: string;
+}): import("react").JSX.Element;
+/** Problems found in the project's files, as a panel. */
+export declare function IssuesPanel({ issues, title }: {
+    issues: Issue[];
+    title?: string;
+}): import("react").JSX.Element | null;

package/dist/viewer-lib/types/viewer/src/components/markdown.d.ts

@@ -0,0 +1,8 @@
+/** http, https, mailto or relative. Browsers drop whitespace and control characters inside a scheme, so do we. */
+export declare function isSafeHref(href: string): boolean;
+export declare function renderMarkdown(text: string): string;
+/** Markdown from the project's own files (guidelines, notes, descriptions). */
+export declare function Markdown({ text, className }: {
+    text: string;
+    className?: string;
+}): import("react").JSX.Element;

package/dist/viewer-lib/types/viewer/src/components/search-button.d.ts

@@ -0,0 +1,6 @@
+export declare function openPalette(): void;
+/** Opens ⌘K. As tall as the buttons next to it; drops the label on narrow screens. */
+export declare function SearchButton({ width, label }: {
+    width?: number;
+    label?: string;
+}): import("react").JSX.Element;

package/dist/viewer-lib/types/viewer/src/components/slide-panel.d.ts

@@ -0,0 +1,11 @@
+import type { ReactNode } from 'react';
+/**
+ * A side panel that slides open and shut. The wrapper animates its width while
+ * the content keeps its own, so nothing inside reflows mid-animation.
+ */
+export declare function SlidePanel({ open, side, width, children, }: {
+    open: boolean;
+    side: 'left' | 'right';
+    width: number;
+    children: ReactNode;
+}): import("react").JSX.Element;

package/dist/viewer-lib/types/viewer/src/components/theme-menu.d.ts

@@ -0,0 +1 @@
+export declare function ThemeMenu(): import("react").JSX.Element;

package/dist/viewer-lib/types/viewer/src/components/topbar.d.ts

@@ -0,0 +1,8 @@
+import { type ReactNode } from 'react';
+/** A 52px bar across the top; pages that fill the screen compose their own content into it. */
+export declare function Bar({ children, className }: {
+    children: ReactNode;
+    className?: string;
+}): import("react").JSX.Element;
+/** The app's top bar: project, sections, search and appearance. */
+export declare function AppTopBar(): import("react").JSX.Element;

package/dist/viewer-lib/types/viewer/src/components/wordmark.d.ts

@@ -0,0 +1,7 @@
+export declare function Mark({ size }: {
+    size?: number;
+}): import("react").JSX.Element;
+export declare function Wordmark({ name, version }: {
+    name?: string;
+    version?: string;
+}): import("react").JSX.Element;

package/dist/viewer-lib/types/viewer/src/lib/api.d.ts

@@ -0,0 +1,14 @@
+import { QueryClient } from '@tanstack/react-query';
+import { type ViewerKeys } from './viewer';
+export { ApiError } from './source';
+/** A live source refetches on every change it announces; the others load once. */
+export declare function createQueryClient(live: boolean): QueryClient;
+/** Nothing in single-canvas mode needs the project. */
+export declare function useProject(): import("@tanstack/react-query").UseQueryResult<import("../../../src/shared/types").ProjectInfo, Error>;
+export declare function useCanvas(id: string, enabled?: boolean): import("@tanstack/react-query").UseQueryResult<import("../../../src/shared/types").CanvasDoc, Error>;
+/** Null when the project has no design system. */
+export declare function useSystem(enabled?: boolean): import("@tanstack/react-query").UseQueryResult<import("../../../src/shared/types").SystemDoc | null, Error>;
+/** A file of the design system. */
+export declare function useSource(path: string | null, unit?: string): import("@tanstack/react-query").UseQueryResult<string, Error>;
+/** Keep queries fresh from the preview server's event stream. */
+export declare function connectEvents(queryClient: QueryClient, keys: ViewerKeys): () => void | undefined;

package/dist/viewer-lib/types/viewer/src/lib/cn.d.ts

@@ -0,0 +1 @@
+export declare function cn(...parts: Array<string | false | null | undefined>): string;

package/dist/viewer-lib/types/viewer/src/lib/copy.d.ts

@@ -0,0 +1 @@
+export declare function copyText(text: string, label?: string): Promise<void>;

package/dist/viewer-lib/types/viewer/src/lib/focus.d.ts

@@ -0,0 +1,2 @@
+export declare function requestFocus(canvas: string, item: string): void;
+export declare function takeFocus(canvas: string): string | null;

package/dist/viewer-lib/types/viewer/src/lib/format.d.ts

@@ -0,0 +1,3 @@
+export declare function relativeTime(ms: number): string;
+export declare function bytes(size: number): string;
+export declare function plural(count: number, one: string, many?: string): string;

package/dist/viewer-lib/types/viewer/src/lib/frames.d.ts

@@ -0,0 +1,25 @@
+import type { RuntimeMessage, Theme, ViewerMessage } from '../../../src/shared/types';
+type Handler = (message: RuntimeMessage) => void;
+export declare function listenToFrame(frame: HTMLIFrameElement, handler: Handler): () => void;
+type Outgoing = ViewerMessage extends infer M ? M extends {
+    source: 'design-viewer';
+} ? Omit<M, 'source'> : never : never;
+export declare function sendToFrame(frame: HTMLIFrameElement | null, message: Outgoing): void;
+/** Tell a frame it sits on the canvas, so it hands the wheel to the viewer. */
+export declare function claimWheel(frame: HTMLIFrameElement | null): void;
+export declare function sendTheme(frame: HTMLIFrameElement | null, theme: Theme): void;
+/** Load the frame again; works whatever origin it is on. */
+export declare function reloadFrame(frame: HTMLIFrameElement | null): void;
+/**
+ * Where the dev server's frames load from. Browsers give each site its own
+ * process, so frames served from the viewer's twin host (localhost ↔ 127.0.0.1,
+ * both reach the same server) run their scripts and animations off the viewer's
+ * thread: a canvas full of live screens still pans smoothly. Any other host,
+ * and static builds, keep frames on the viewer's origin.
+ */
+export declare const FRAME_ORIGIN: string;
+/** A frame URL with the theme it should open in. */
+export declare function frameSrc(url: string, theme: Theme, extra?: Record<string, string>): string;
+/** Absolute URL for opening a frame in a new tab. */
+export declare function absoluteUrl(url: string): string;
+export {};

package/dist/viewer-lib/types/viewer/src/lib/platform.d.ts

@@ -0,0 +1,3 @@
+export declare const IS_MAC: boolean;
+/** The shortcut modifier as the user's keyboard labels it. */
+export declare const MOD_KEY: string;

package/dist/viewer-lib/types/viewer/src/lib/source.d.ts

@@ -0,0 +1,43 @@
+import type { CanvasDoc, ProjectInfo, SystemDoc } from '../../../src/shared/types';
+declare global {
+    interface Window {
+        __DESIGN_STATIC__?: boolean;
+        __DESIGN_CANVAS_READY__?: boolean;
+    }
+}
+/** A site made by `design build`: JSON files instead of the API, hash routing, no live updates. */
+export declare const STATIC_SITE: boolean;
+/**
+ * Where the viewer gets a project from. Docs keep the URLs they were built
+ * with; relative ones (`_s/…`, `_f/…`, `_snap/…`) resolve against the `base`
+ * their unit comes with, so frames and images can live on another host.
+ */
+export interface ViewerSource {
+    /** Keep queries fresh from the preview server's `/api/events` stream. */
+    live: boolean;
+    project(): Promise<ProjectInfo>;
+    canvas(id: string): Promise<{
+        doc: CanvasDoc;
+        base: string;
+    }>;
+    /** Null when the project has no design system. */
+    system(): Promise<{
+        doc: SystemDoc;
+        base: string;
+    } | null>;
+    /** The text of a project file; `unit` is `system` or `canvas/<id>`. */
+    source(path: string, unit: string): Promise<string>;
+}
+export declare class ApiError extends Error {
+    readonly status: number;
+    constructor(status: number, message: string);
+}
+export declare const localSource: ViewerSource;
+/** The JSON files of a `design build` site, relative to its root. */
+export declare const staticSource: ViewerSource;
+/** `url` against a unit's base; an empty base leaves it as the doc has it. */
+export declare function resolveUrl(url: string, base: string): string;
+/** A canvas with its frame, snapshot and image URLs resolved against its unit's base. */
+export declare function resolveCanvas(doc: CanvasDoc, base: string): CanvasDoc;
+/** A design system with its specimen and asset URLs resolved against the system unit's base. */
+export declare function resolveSystem(doc: SystemDoc, base: string): SystemDoc;

package/dist/viewer-lib/types/viewer/src/lib/store.d.ts

@@ -0,0 +1,10 @@
+/** A tiny observable value for state shared outside React's tree. */
+export declare class Store<T> {
+    private value;
+    private listeners;
+    constructor(value: T);
+    get: () => T;
+    set: (next: T | ((prev: T) => T)) => void;
+    subscribe: (listener: () => void) => () => void;
+}
+export declare function useStore<T, S = T>(store: Store<T>, select?: (value: T) => S): S;

package/dist/viewer-lib/types/viewer/src/lib/theme.d.ts

@@ -0,0 +1,6 @@
+export type ThemePref = 'system' | 'light' | 'dark';
+export type Theme = 'light' | 'dark';
+export declare function setThemePref(value: ThemePref): void;
+export declare function useThemePref(): ThemePref;
+/** The theme the app shows: the saved choice, or the system's. */
+export declare function useTheme(): Theme;