swatch-token 0.0.0-stage → 0.1.0

package/dist/server/files.d.ts

@@ -0,0 +1,16 @@
+import { type Change, type Edit } from "./stylesheet.js";
+export declare function readSheet(file: string): {
+    tokens: Map<string, {
+        light?: string;
+        dark?: string;
+    }>;
+    dark: import("./stylesheet.ts").DarkSelector | null;
+};
+/** The whole batch on one read and one write, so a save of forty values is
+ *  one change to the file and one hot reload. A failed check writes
+ *  nothing. */
+export declare function write(file: string, edits: Edit[]): Change[];
+/** Several files' batches as one save: every file's new text is worked out
+ *  before any is written, and if a write fails part-way the files already
+ *  written are put back as they were. Either all of them change or none. */
+export declare function writeAll(batches: Map<string, Edit[]>): Change[];

package/dist/server/guard.d.ts

@@ -0,0 +1,13 @@
+import type { IncomingMessage } from "node:http";
+export type Trust = {
+    /** Vite's `server.allowedHosts`: true for any host, or a list (a leading "." allows subdomains) */
+    allowedHosts?: true | string[];
+    /** origins named in Swatch's options, e.g. "https://my-tunnel.example" */
+    allowedOrigins?: string[];
+};
+/** Why a write is refused, or null when it may go ahead. */
+export declare function refuseWrite(req: Pick<IncomingMessage, "headers"> & {
+    socket: {
+        remoteAddress?: string;
+    };
+}, trust?: Trust): string | null;

package/dist/server/project.d.ts

@@ -0,0 +1,71 @@
+import { THEMES, type Change, type DarkSelector, type Edit, type Theme } from "./stylesheet.js";
+export type Options = {
+    /** The stylesheet(s) the tokens live in, from the project root. Left
+     *  out, every stylesheet in the project that declares custom properties
+     *  on a theme is used. */
+    css?: string | string[];
+    /** Where uses are counted, from the project root. Default: the whole
+     *  project, without the folders below. */
+    src?: string;
+    /** Section titles for the panel, each with a pattern its token names
+     *  match, tried in order. Left out, tokens are grouped by the first
+     *  word of their name. */
+    groups?: Record<string, RegExp | string>;
+    /** Show "Save & send to agent" and "Figma sync", which leave requests in
+     *  `.swatch/requests.jsonl` for a coding agent to pick up. */
+    agent?: boolean;
+    /** Folders, from the project root, that are neither searched for
+     *  stylesheets nor counted for uses (node_modules, hidden folders and the
+     *  build output are left out already). */
+    ignore?: string[];
+    /** Origins besides the dev server's own that may save, e.g. a tunnel's
+     *  "https://my-tunnel.example" (hosts in Vite's `server.allowedHosts`
+     *  are trusted already). */
+    allowedOrigins?: string[];
+};
+export type Token = {
+    name: string;
+    light?: string;
+    dark?: string;
+    /** the stylesheet each value is in, from the project root */
+    file: string;
+    /** how its stylesheet selects the dark theme, where that differs from the project's */
+    darkAt?: DarkSelector;
+    uses: {
+        file: string;
+        n: number;
+    }[];
+};
+export type Sheet = {
+    files: string[];
+    tokens: Token[];
+    dark: DarkSelector | null;
+    groups: [string, string][] | null;
+    agent: boolean;
+    changes?: Change[];
+};
+export declare class Project {
+    readonly root: string;
+    readonly options: Options;
+    /** folders left out of every search, absolute */
+    private readonly skip;
+    private watching;
+    private sheets;
+    private sources;
+    constructor(root: string, options?: Options, skip?: string[]);
+    private get src();
+    watch(): void;
+    /** A file changed (or was added or removed: `listChanged`). */
+    forget(path: string, listChanged: boolean): void;
+    /** The stylesheets that hold tokens: the ones named, or every one in the
+     *  project that declares a custom property on a theme. */
+    stylesheets(): string[];
+    read(): Sheet;
+    /** Sends each edit to the stylesheet that holds the token in that theme;
+     *  failing that, the one that holds it in the other theme; failing that
+     *  (a new token), the one with the most tokens. Every edit is checked,
+     *  and every file's new text worked out, before any file is touched. */
+    write(edits: Edit[]): Change[];
+}
+export { THEMES };
+export type { Change, Edit, Theme };

package/dist/server/requests.d.ts

@@ -0,0 +1,42 @@
+import { type Change, type Theme } from "./stylesheet.js";
+export type Request = {
+    kind: "commit";
+    changes: Change[];
+} | {
+    kind: "figma-sync";
+    figma: string;
+};
+export type Queued = Request & {
+    id: string;
+    at: string;
+    files: string[];
+};
+export type Proposal = Record<string, Partial<Record<Theme, string>>>;
+export declare class Queue {
+    readonly dir: string;
+    readonly incoming: string;
+    constructor(root: string);
+    /** The queue holds only what was checked field by field: nothing a
+     *  caller adds to the body, and no field of ours a caller can replace. */
+    add(r: Request, files: string[]): {
+        id: string;
+    };
+    /** What the agent left, or null (also while it is half written). */
+    take(): unknown;
+    clear(): void;
+    private get file();
+    private seen;
+    /** The requests no agent has dealt with yet, oldest first. A request that
+     *  has been dealt with is taken out of the file (below), so the file only
+     *  ever holds what is pending, and stays small. */
+    pending(): Queued[];
+    /** Takes a request out of the queue, as dealt with, and notes it (with
+     *  its note) in done.jsonl, which keeps the last hundred. The panel may
+     *  append a request while this rewrites the file: the file is read again
+     *  and the rewrite retried if it grew in between, so no request is lost. */
+    resolve(id: string, note?: string): void;
+    /** Leaves values for the panel to load as unsaved edits: every one
+     *  checked as a write would be, and the file put in place whole, so the
+     *  panel never reads half of it. Returns how many values. */
+    propose(edits: Proposal, note?: string): number;
+}

package/dist/server/stylesheet.d.ts

@@ -0,0 +1,51 @@
+import { type AtRule, type Declaration, type Root, type Rule } from "postcss";
+export type Theme = "light" | "dark";
+export declare const THEMES: Theme[];
+export type Edit = {
+    theme: Theme;
+    name: string;
+    value: string;
+};
+export type Change = {
+    name: string;
+    theme: Theme;
+    from: string | null;
+    to: string | null;
+};
+/** A block that holds a theme's declarations: a rule, or an `@theme` block. */
+type Block = Rule | AtRule;
+type Found = {
+    decl: Declaration;
+    theme: Theme;
+};
+export type DarkSelector = {
+    selector: string;
+    media: string | null;
+};
+export type Parsed = {
+    root: Root;
+    decls: Found[];
+    blocks: Record<Theme, Block[]>;
+    dark: DarkSelector | null;
+};
+export declare function parse(css: string, from: string): Parsed;
+/** A declaration's value as the panel shows it. */
+export declare const shown: (d: Declaration | undefined) => string | null;
+/** Every custom property of the two themes in one stylesheet. The last
+ *  declaration in a theme is the one the cascade uses. */
+export declare function readText(css: string, from?: string): {
+    tokens: Map<string, {
+        light?: string;
+        dark?: string;
+    }>;
+    dark: DarkSelector | null;
+};
+export declare function check(e: Edit): void;
+/** The stylesheet with a batch of edits applied, and what each changed. A
+ *  failed check, or a result that would not read back as a stylesheet,
+ *  throws and gives nothing. */
+export declare function writeText(css: string, edits: Edit[], from?: string): {
+    css: string;
+    changes: Change[];
+};
+export {};

package/dist/vite.d.ts

@@ -0,0 +1,4 @@
+import type { Plugin } from "vite";
+import { type Options } from "./server/project.js";
+export type { Options };
+export default function swatch(options?: Options): Plugin;