@cauthyhq/node 0.0.0-stage → 1.0.0

package/dist/theme.d.mts

@@ -0,0 +1,183 @@
+/** How an application looks on Cauthy's hosted pages. Every value is optional. */
+/** One font file the application serves: a family in one weight (or a range) and one style. */
+interface ThemeFont {
+    family: string;
+    /** An https address of a `.woff2` file. It must answer with `Access-Control-Allow-Origin` for Cauthy's origin. */
+    url: string;
+    /** `400`, or `"100 900"` for a variable font. Default: 400. */
+    weight?: number | string;
+    style?: 'normal' | 'italic';
+}
+/** What an application says on its sign-in page, in one language. */
+interface ThemeTexts {
+    /** Replaces "Sign in". */
+    heading?: string;
+    /** Replaces "to continue to …". */
+    subheading?: string;
+    /** The messages of the split layout's panel, shown one at a time (up to 5). */
+    panel?: string[];
+    /** Links at the foot of the split layout: privacy, terms (up to 4). */
+    links?: {
+        label: string;
+        url: string;
+    }[];
+}
+interface CauthyTheme {
+    /** The page. Colours are `#rrggbb` or `rgba(r, g, b, a)`. */
+    background?: string;
+    /** The card, and inputs. */
+    surface?: string;
+    /** Headings and what is typed. */
+    text?: string;
+    /** Paragraphs, labels, small print. */
+    textMuted?: string;
+    border?: string;
+    /** The fields and the secondary buttons, when they are not the card's colours. */
+    inputBackground?: string;
+    inputBorder?: string;
+    /** The main button, and what is written on it. */
+    primary?: string;
+    primaryText?: string;
+    /** Links, and the focus ring. */
+    accent?: string;
+    error?: string;
+    errorBackground?: string;
+    success?: string;
+    successBackground?: string;
+    /** Corners of cards and inputs, in pixels (0–40). */
+    radius?: number;
+    /** Corners of buttons, in pixels (0–40). */
+    buttonRadius?: number;
+    /** A CSS font-family list: the application's typeface first, a system font after it. */
+    fontFamily?: string;
+    /** The files of the typefaces `fontFamily` names, for people who do not have them installed. */
+    fonts?: ThemeFont[];
+    /** An image shown where "Cauthy" is, over https. */
+    logoUrl?: string;
+    /**
+     * How the sign-in pages are laid out: `card` (the default, one card in the
+     * middle) or `split` (the form on one side, a panel that presents the
+     * application on the other).
+     */
+    layout?: 'card' | 'split';
+    /** The colours the split layout's backdrop blends, one to four. */
+    panelColors?: string[];
+    /** The colour of what is written on the panel. */
+    panelText?: string;
+    /** An https image shown over the panel's messages. */
+    panelIconUrl?: string;
+    /** The application's own words on the sign-in page, by language (`en`, `es`). */
+    texts?: Record<string, ThemeTexts>;
+    /**
+     * The application's Stackmyth tokens (`--sm-*`), from `tokensFromStackmyth`.
+     * Cauthy's pages are drawn with Stackmyth's components, so these make its
+     * buttons and fields the application's own. They are laid over the named values.
+     */
+    tokens?: Record<string, string>;
+}
+interface StackmythThemeOptions {
+    /**
+     * The named theme to read, when the stylesheet keeps several under
+     * `[data-theme=…]` (`"acme"`). Without it only what applies to every
+     * page (`:root`) is read.
+     */
+    theme?: string;
+    /** Which of the application's two modes to take. Default: `light`. */
+    mode?: 'light' | 'dark';
+    logoUrl?: string;
+}
+interface ImportedTheme {
+    theme: CauthyTheme;
+    /** Tokens that were there and could not be carried over, and why. */
+    warnings: string[];
+}
+interface StackmythTokens {
+    /** Every `--sm-*` token the stylesheets set for the page, ready for `theme.tokens`. */
+    tokens: Record<string, string>;
+    /** Tokens that were there and Cauthy would not take, and why. */
+    warnings: string[];
+}
+/**
+ * Reads an application's Stackmyth tokens out of its stylesheets: every
+ * `--sm-*` custom property its theme sets, in the order the sheets are given
+ * (a later one wins). Its own names — a brand palette the tokens point at —
+ * are written in, so what comes out stands on Stackmyth's names alone.
+ *
+ * Cauthy's sign-in pages are drawn with Stackmyth's components: these tokens
+ * are what makes them look like the application.
+ */
+declare function tokensFromStackmyth(css: string | string[], options?: StackmythThemeOptions): StackmythTokens;
+/** A colour as Cauthy takes it — `#rrggbb` or `rgba(…)` — or null when it is none it can read. */
+declare function toColor(value: string): string | null;
+/**
+ * Reads an application's Stackmyth theme out of its stylesheets.
+ *
+ * Give it the CSS that declares the tokens, in the order the application
+ * loads it — Stackmyth's own (`@stackmyth/core/core.vars.css`, or a theme
+ * file) and then the application's brand file that re-points them. Tokens
+ * that point at the application's own variables are followed. The
+ * application's dark mode is left out unless asked for.
+ */
+declare function themeFromStackmyth(css: string | string[], options?: StackmythThemeOptions): ImportedTheme;
+/** The values of a theme a stylesheet can say. */
+type ThemeField = 'background' | 'surface' | 'text' | 'textMuted' | 'border' | 'inputBackground' | 'inputBorder' | 'primary' | 'primaryText' | 'accent' | 'error' | 'errorBackground' | 'success' | 'successBackground' | 'radius' | 'buttonRadius' | 'fontFamily';
+/** How a stylesheet names its look: Stackmyth's tokens, shadcn/ui's (and Tailwind's), or the application's own. */
+type CssFormat = 'stackmyth' | 'shadcn' | 'custom';
+interface CssThemeOptions {
+    /** Which names to read. Default: `auto`, told from the stylesheet itself. */
+    format?: CssFormat | 'auto';
+    /** Which of the application's two modes to take. Default: `light`. */
+    mode?: 'light' | 'dark';
+    /** The named theme to read, when the stylesheet keeps several under `[data-theme=…]`. */
+    theme?: string;
+    /** For `custom`: the variable each value is read from, `{ primary: '--brand' }`. */
+    map?: Partial<Record<ThemeField, string>>;
+}
+interface CssImportedTheme extends ImportedTheme {
+    /** The names that were read. */
+    format: CssFormat;
+}
+/** The custom properties a stylesheet sets for the page, by name: what a person picks from to map their own. */
+declare function cssVariables(css: string | string[], options?: Pick<CssThemeOptions, 'mode' | 'theme'>): string[];
+/**
+ * Reads an application's look out of its stylesheets, whatever names it uses:
+ * Stackmyth's tokens, shadcn/ui's (`--primary`, `--radius`, on Tailwind 3 or
+ * 4), or the application's own variables given in `map`. What comes out is a
+ * theme of named values, never CSS.
+ */
+declare function themeFromCss(css: string | string[], options?: CssThemeOptions): CssImportedTheme;
+/**
+ * A theme as the CSS variables of `@cauthyhq/react/styles.css` (stage 5) (`--cauthy-*`), for
+ * the forms an application shows on its own pages. The page's own background,
+ * the layout and the words are Cauthy's pages' matter, and left out.
+ */
+declare function themeVariables(theme: CauthyTheme): Record<string, string>;
+/** A theme as Cauthy's API names its values. */
+declare function toWire(theme: CauthyTheme): Record<string, unknown>;
+/** A theme as Cauthy answers it, in this package's names. */
+declare function fromWire(wire: Record<string, unknown>): CauthyTheme;
+interface PushThemeOptions {
+    /** Cauthy's address. Default: `CAUTHY_ISSUER`. */
+    issuer?: string;
+    /** The application's client id. Default: `CAUTHY_CLIENT_ID`. */
+    clientId?: string;
+    /** The workspace's slug. Default: `CAUTHY_TENANT`. */
+    tenant?: string;
+    /**
+     * A personal access token with `oauth_clients:manage`. Default:
+     * `CAUTHY_TOKEN`. It belongs in the deploy pipeline, never in the application.
+     */
+    token?: string;
+    theme: CauthyTheme;
+    fetch?: typeof fetch;
+    /** How long the call may take, in milliseconds, before it fails with a `TimeoutError`. Default: 5000. */
+    timeoutMs?: number;
+}
+/**
+ * Gives the application its look on Cauthy's pages. It replaces the theme: a
+ * value left out goes back to Cauthy's own. Run it when the brand changes —
+ * from a script or the deploy — not on every request.
+ */
+declare function pushTheme(o: PushThemeOptions): Promise<void>;
+
+export { type CauthyTheme, type CssFormat, type CssImportedTheme, type CssThemeOptions, type ImportedTheme, type PushThemeOptions, type StackmythThemeOptions, type StackmythTokens, type ThemeField, type ThemeFont, type ThemeTexts, cssVariables, fromWire, pushTheme, themeFromCss, themeFromStackmyth, themeVariables, toColor, toWire, tokensFromStackmyth };

package/dist/theme.d.ts

@@ -0,0 +1,183 @@
+/** How an application looks on Cauthy's hosted pages. Every value is optional. */
+/** One font file the application serves: a family in one weight (or a range) and one style. */
+interface ThemeFont {
+    family: string;
+    /** An https address of a `.woff2` file. It must answer with `Access-Control-Allow-Origin` for Cauthy's origin. */
+    url: string;
+    /** `400`, or `"100 900"` for a variable font. Default: 400. */
+    weight?: number | string;
+    style?: 'normal' | 'italic';
+}
+/** What an application says on its sign-in page, in one language. */
+interface ThemeTexts {
+    /** Replaces "Sign in". */
+    heading?: string;
+    /** Replaces "to continue to …". */
+    subheading?: string;
+    /** The messages of the split layout's panel, shown one at a time (up to 5). */
+    panel?: string[];
+    /** Links at the foot of the split layout: privacy, terms (up to 4). */
+    links?: {
+        label: string;
+        url: string;
+    }[];
+}
+interface CauthyTheme {
+    /** The page. Colours are `#rrggbb` or `rgba(r, g, b, a)`. */
+    background?: string;
+    /** The card, and inputs. */
+    surface?: string;
+    /** Headings and what is typed. */
+    text?: string;
+    /** Paragraphs, labels, small print. */
+    textMuted?: string;
+    border?: string;
+    /** The fields and the secondary buttons, when they are not the card's colours. */
+    inputBackground?: string;
+    inputBorder?: string;
+    /** The main button, and what is written on it. */
+    primary?: string;
+    primaryText?: string;
+    /** Links, and the focus ring. */
+    accent?: string;
+    error?: string;
+    errorBackground?: string;
+    success?: string;
+    successBackground?: string;
+    /** Corners of cards and inputs, in pixels (0–40). */
+    radius?: number;
+    /** Corners of buttons, in pixels (0–40). */
+    buttonRadius?: number;
+    /** A CSS font-family list: the application's typeface first, a system font after it. */
+    fontFamily?: string;
+    /** The files of the typefaces `fontFamily` names, for people who do not have them installed. */
+    fonts?: ThemeFont[];
+    /** An image shown where "Cauthy" is, over https. */
+    logoUrl?: string;
+    /**
+     * How the sign-in pages are laid out: `card` (the default, one card in the
+     * middle) or `split` (the form on one side, a panel that presents the
+     * application on the other).
+     */
+    layout?: 'card' | 'split';
+    /** The colours the split layout's backdrop blends, one to four. */
+    panelColors?: string[];
+    /** The colour of what is written on the panel. */
+    panelText?: string;
+    /** An https image shown over the panel's messages. */
+    panelIconUrl?: string;
+    /** The application's own words on the sign-in page, by language (`en`, `es`). */
+    texts?: Record<string, ThemeTexts>;
+    /**
+     * The application's Stackmyth tokens (`--sm-*`), from `tokensFromStackmyth`.
+     * Cauthy's pages are drawn with Stackmyth's components, so these make its
+     * buttons and fields the application's own. They are laid over the named values.
+     */
+    tokens?: Record<string, string>;
+}
+interface StackmythThemeOptions {
+    /**
+     * The named theme to read, when the stylesheet keeps several under
+     * `[data-theme=…]` (`"acme"`). Without it only what applies to every
+     * page (`:root`) is read.
+     */
+    theme?: string;
+    /** Which of the application's two modes to take. Default: `light`. */
+    mode?: 'light' | 'dark';
+    logoUrl?: string;
+}
+interface ImportedTheme {
+    theme: CauthyTheme;
+    /** Tokens that were there and could not be carried over, and why. */
+    warnings: string[];
+}
+interface StackmythTokens {
+    /** Every `--sm-*` token the stylesheets set for the page, ready for `theme.tokens`. */
+    tokens: Record<string, string>;
+    /** Tokens that were there and Cauthy would not take, and why. */
+    warnings: string[];
+}
+/**
+ * Reads an application's Stackmyth tokens out of its stylesheets: every
+ * `--sm-*` custom property its theme sets, in the order the sheets are given
+ * (a later one wins). Its own names — a brand palette the tokens point at —
+ * are written in, so what comes out stands on Stackmyth's names alone.
+ *
+ * Cauthy's sign-in pages are drawn with Stackmyth's components: these tokens
+ * are what makes them look like the application.
+ */
+declare function tokensFromStackmyth(css: string | string[], options?: StackmythThemeOptions): StackmythTokens;
+/** A colour as Cauthy takes it — `#rrggbb` or `rgba(…)` — or null when it is none it can read. */
+declare function toColor(value: string): string | null;
+/**
+ * Reads an application's Stackmyth theme out of its stylesheets.
+ *
+ * Give it the CSS that declares the tokens, in the order the application
+ * loads it — Stackmyth's own (`@stackmyth/core/core.vars.css`, or a theme
+ * file) and then the application's brand file that re-points them. Tokens
+ * that point at the application's own variables are followed. The
+ * application's dark mode is left out unless asked for.
+ */
+declare function themeFromStackmyth(css: string | string[], options?: StackmythThemeOptions): ImportedTheme;
+/** The values of a theme a stylesheet can say. */
+type ThemeField = 'background' | 'surface' | 'text' | 'textMuted' | 'border' | 'inputBackground' | 'inputBorder' | 'primary' | 'primaryText' | 'accent' | 'error' | 'errorBackground' | 'success' | 'successBackground' | 'radius' | 'buttonRadius' | 'fontFamily';
+/** How a stylesheet names its look: Stackmyth's tokens, shadcn/ui's (and Tailwind's), or the application's own. */
+type CssFormat = 'stackmyth' | 'shadcn' | 'custom';
+interface CssThemeOptions {
+    /** Which names to read. Default: `auto`, told from the stylesheet itself. */
+    format?: CssFormat | 'auto';
+    /** Which of the application's two modes to take. Default: `light`. */
+    mode?: 'light' | 'dark';
+    /** The named theme to read, when the stylesheet keeps several under `[data-theme=…]`. */
+    theme?: string;
+    /** For `custom`: the variable each value is read from, `{ primary: '--brand' }`. */
+    map?: Partial<Record<ThemeField, string>>;
+}
+interface CssImportedTheme extends ImportedTheme {
+    /** The names that were read. */
+    format: CssFormat;
+}
+/** The custom properties a stylesheet sets for the page, by name: what a person picks from to map their own. */
+declare function cssVariables(css: string | string[], options?: Pick<CssThemeOptions, 'mode' | 'theme'>): string[];
+/**
+ * Reads an application's look out of its stylesheets, whatever names it uses:
+ * Stackmyth's tokens, shadcn/ui's (`--primary`, `--radius`, on Tailwind 3 or
+ * 4), or the application's own variables given in `map`. What comes out is a
+ * theme of named values, never CSS.
+ */
+declare function themeFromCss(css: string | string[], options?: CssThemeOptions): CssImportedTheme;
+/**
+ * A theme as the CSS variables of `@cauthyhq/react/styles.css` (stage 5) (`--cauthy-*`), for
+ * the forms an application shows on its own pages. The page's own background,
+ * the layout and the words are Cauthy's pages' matter, and left out.
+ */
+declare function themeVariables(theme: CauthyTheme): Record<string, string>;
+/** A theme as Cauthy's API names its values. */
+declare function toWire(theme: CauthyTheme): Record<string, unknown>;
+/** A theme as Cauthy answers it, in this package's names. */
+declare function fromWire(wire: Record<string, unknown>): CauthyTheme;
+interface PushThemeOptions {
+    /** Cauthy's address. Default: `CAUTHY_ISSUER`. */
+    issuer?: string;
+    /** The application's client id. Default: `CAUTHY_CLIENT_ID`. */
+    clientId?: string;
+    /** The workspace's slug. Default: `CAUTHY_TENANT`. */
+    tenant?: string;
+    /**
+     * A personal access token with `oauth_clients:manage`. Default:
+     * `CAUTHY_TOKEN`. It belongs in the deploy pipeline, never in the application.
+     */
+    token?: string;
+    theme: CauthyTheme;
+    fetch?: typeof fetch;
+    /** How long the call may take, in milliseconds, before it fails with a `TimeoutError`. Default: 5000. */
+    timeoutMs?: number;
+}
+/**
+ * Gives the application its look on Cauthy's pages. It replaces the theme: a
+ * value left out goes back to Cauthy's own. Run it when the brand changes —
+ * from a script or the deploy — not on every request.
+ */
+declare function pushTheme(o: PushThemeOptions): Promise<void>;
+
+export { type CauthyTheme, type CssFormat, type CssImportedTheme, type CssThemeOptions, type ImportedTheme, type PushThemeOptions, type StackmythThemeOptions, type StackmythTokens, type ThemeField, type ThemeFont, type ThemeTexts, cssVariables, fromWire, pushTheme, themeFromCss, themeFromStackmyth, themeVariables, toColor, toWire, tokensFromStackmyth };