typewritingclass 0.2.2 → 0.2.3

package/dist/types-FfRD4Hbd.d.ts

@@ -0,0 +1,346 @@
+/**
+ * A wrapper around a runtime-changeable CSS value.
+ *
+ * Instead of baking the value directly into the generated CSS, a
+ * `DynamicValue` is replaced with a CSS custom property reference
+ * (`var(--twc-dN)`). The actual value is applied at runtime through an
+ * inline `style` attribute, allowing it to change without regenerating
+ * the stylesheet.
+ *
+ * Create instances with the {@link dynamic} factory -- do not construct
+ * this interface manually.
+ *
+ * @typeParam T - The underlying value type, constrained to `string | number`.
+ *
+ * @example
+ * ```ts
+ * import { dynamic, bg, dcx } from 'typewritingclass'
+ *
+ * const color = dynamic('#e11d48')
+ * // color._tag    => 'DynamicValue'
+ * // color.__value => '#e11d48'
+ * // color.__id    => '--twc-d0'
+ *
+ * const { className, style } = dcx(bg(color))
+ * // Generated CSS uses var(--twc-d0) instead of the literal color.
+ * // style maps '--twc-d0' to '#e11d48' for the inline style attribute.
+ * ```
+ */
+interface DynamicValue<T extends string | number = string | number> {
+    /** Discriminant tag for runtime type checking. Always `'DynamicValue'`. */
+    _tag: 'DynamicValue';
+    /** The current runtime value (e.g. `'#e11d48'` or `16`). */
+    __value: T;
+    /** The generated CSS custom property name (e.g. `'--twc-d0'`). */
+    __id: string;
+}
+/**
+ * Wraps a value so it becomes a runtime-dynamic CSS custom property.
+ *
+ * The returned {@link DynamicValue} can be passed to any utility that
+ * accepts `DynamicValue` (e.g. `bg`, `p`, `textColor`, `rounded`). When
+ * composed via {@link dcx}, the value is not inlined into the CSS rule;
+ * instead a `var(--twc-dN)` reference is emitted, and the concrete value
+ * is placed in the `style` object so it can be changed at runtime without
+ * touching the stylesheet.
+ *
+ * Each call to `dynamic` allocates a new, globally unique custom property
+ * name (`--twc-d0`, `--twc-d1`, ...).
+ *
+ * @typeParam T - Inferred from the provided value; constrained to `string | number`.
+ * @param value - The initial CSS value (e.g. a color hex string, a pixel value, etc.).
+ * @returns A {@link DynamicValue} wrapping the given value with a unique CSS
+ *          custom property identifier.
+ *
+ * @example Dynamic background color in React
+ * ```ts
+ * import { dcx, bg, p, dynamic } from 'typewritingclass'
+ *
+ * function Banner({ color }: { color: string }) {
+ *   const { className, style } = dcx(p(4), bg(dynamic(color)))
+ *   return <div className={className} style={style} />
+ * }
+ * // CSS: ._xyz { background-color: var(--twc-d0); padding: 1rem; }
+ * // Inline style: --twc-d0: <whatever `color` is at render time>
+ * ```
+ *
+ * @example Dynamic spacing
+ * ```ts
+ * import { dcx, p, dynamic } from 'typewritingclass'
+ *
+ * const spacing = dynamic('2.5rem')
+ * const { className, style } = dcx(p(spacing))
+ * // className => "_a1b2c"
+ * // style     => { '--twc-d0': '2.5rem' }
+ * // CSS: ._a1b2c { padding: var(--twc-d0); }
+ * ```
+ */
+declare function dynamic<T extends string | number>(value: T): DynamicValue<T>;
+/**
+ * Type-guard that checks whether an unknown value is a {@link DynamicValue}.
+ *
+ * Useful inside utilities and the `css` tagged-template implementation to
+ * decide whether to emit a `var()` reference or inline the value directly.
+ *
+ * @param v - Any value to test.
+ * @returns `true` if `v` is a `DynamicValue`, narrowing its type accordingly.
+ *
+ * @example
+ * ```ts
+ * import { dynamic, isDynamic } from 'typewritingclass'
+ *
+ * const val = dynamic('#ff0000')
+ * isDynamic(val)       // => true
+ * isDynamic('#ff0000') // => false
+ * isDynamic(42)        // => false
+ * isDynamic(null)      // => false
+ * ```
+ */
+declare function isDynamic(v: unknown): v is DynamicValue;
+
+declare const __brand: unique symbol;
+/**
+ * Creates a nominal/branded type from a base type.
+ *
+ * Branded types look like their base type at runtime but are distinct at the
+ * type level, preventing accidental misuse (e.g. passing a color where a
+ * spacing value is expected).
+ *
+ * @example
+ * ```ts
+ * type Meters = Brand<number, 'meters'>
+ * type Seconds = Brand<number, 'seconds'>
+ *
+ * const d: Meters = 5 as Meters
+ * const t: Seconds = d // Type error — distinct brands!
+ * ```
+ */
+type Brand<T, B extends string> = T & {
+    readonly [__brand]: B;
+};
+/**
+ * A branded CSS color value — hex, `rgb()`, `hsl()`, CSS variable, etc.
+ *
+ * Theme color tokens (e.g. `blue[500]`) carry this brand. Raw color strings
+ * are also accepted alongside `CSSColor` since utility functions accept both.
+ */
+type CSSColor = Brand<string, 'css-color'>;
+/**
+ * A branded CSS length value — `rem`, `px`, `em`, `%`, `vh`, `vw`, etc.
+ *
+ * Theme spacing, size, and border-radius tokens carry this brand.
+ */
+type CSSLength = Brand<string, 'css-length'>;
+/**
+ * A branded CSS shadow value — `box-shadow` definition string.
+ *
+ * Theme shadow tokens (e.g. `lg` from `theme/shadows`) carry this brand.
+ */
+type CSSShadow = Brand<string, 'css-shadow'>;
+/**
+ * A branded CSS font-weight value — numeric string like `'400'` or `'700'`.
+ *
+ * Theme font weight tokens (e.g. `bold`, `semibold`) carry this brand.
+ */
+type CSSFontWeight = Brand<string, 'css-font-weight'>;
+/** Shorthand for any DynamicValue — used in utility input types. */
+type DynamicValueAny = DynamicValue;
+/**
+ * Input type for color utilities ({@link bg}, {@link textColor}, {@link borderColor}).
+ *
+ * Accepts theme color tokens (`CSSColor`), raw CSS color strings, or dynamic values.
+ */
+type ColorInput = CSSColor | string | DynamicValueAny;
+/**
+ * Input type for spacing utilities ({@link p}, {@link m}, {@link gap}).
+ *
+ * Accepts a theme scale number (`4` → `1rem`), a raw CSS length string
+ * (`'1.5rem'`), a theme length token, or a dynamic value.
+ */
+type SpacingInput = number | CSSLength | string | DynamicValueAny;
+/**
+ * Input type for size utilities ({@link w}, {@link h}, {@link minW}).
+ *
+ * Accepts a theme scale number, a raw CSS string (`'100%'`), a theme size
+ * token (`full`, `screen`), or a dynamic value.
+ */
+type SizeInput = number | CSSLength | string | DynamicValueAny;
+/**
+ * Input type for border-radius utilities ({@link rounded}).
+ *
+ * Accepts a theme radius token (`lg`), a raw CSS string, or a dynamic value.
+ */
+type RadiusInput = CSSLength | string | DynamicValueAny;
+/**
+ * Input type for shadow utilities ({@link shadow}).
+ *
+ * Accepts a theme shadow token (`lg`), a raw CSS string, or a dynamic value.
+ */
+type ShadowInput = CSSShadow | string | DynamicValueAny;
+/**
+ * A self-contained CSS rule produced by utility functions, the {@link css}
+ * helper, or modifier composition.
+ *
+ * `StyleRule` is the fundamental unit of the typewritingclass system. Every
+ * utility (`p`, `bg`, `rounded`, ...) returns a `StyleRule`, and composing
+ * functions like `cx` and `dcx` consume them to generate class names and
+ * register CSS in the global stylesheet.
+ *
+ * You rarely need to construct a `StyleRule` by hand -- use the provided
+ * utilities or the `css` tagged-template helper instead.
+ *
+ * @example Inspecting a rule returned by a utility
+ * ```ts
+ * import { p } from 'typewritingclass'
+ *
+ * const rule = p(4)
+ * // rule.declarations  => { padding: '1rem' }
+ * // rule.selectors      => []
+ * // rule.mediaQueries   => []
+ * ```
+ *
+ * @example A rule wrapped with a modifier
+ * ```ts
+ * import { p, hover } from 'typewritingclass'
+ *
+ * const rule = hover(p(4))
+ * // rule.selectors => [':hover']
+ * // CSS: .className:hover { padding: 1rem; }
+ * ```
+ */
+interface StyleRule {
+    /** Discriminant tag used for runtime type narrowing. Always `'StyleRule'`. */
+    _tag: 'StyleRule';
+    /**
+     * A map of CSS property-value pairs that this rule will emit.
+     *
+     * Keys are CSS property names (e.g. `'padding'`, `'background-color'`),
+     * and values are their corresponding CSS values (e.g. `'1rem'`, `'#3b82f6'`).
+     */
+    declarations: Record<string, string>;
+    /**
+     * Pseudo-class or pseudo-element selectors appended to the generated
+     * class name (e.g. `[':hover']`, `[':focus', ':active']`).
+     *
+     * An empty array means the rule applies unconditionally.
+     */
+    selectors: string[];
+    /**
+     * Media query strings that wrap the generated rule
+     * (e.g. `['(min-width: 768px)']`).
+     *
+     * An empty array means no `@media` wrapper is emitted.
+     */
+    mediaQueries: string[];
+    /**
+     * CSS custom property bindings for dynamic (runtime-changeable) values.
+     *
+     * When present, the generated CSS references `var(--twc-dN)` and these
+     * bindings must be applied as inline `style` on the element (via `dcx`).
+     * Keys are CSS custom property names (e.g. `'--twc-d0'`), values are
+     * the current runtime values (e.g. `'#ff0000'`).
+     */
+    dynamicBindings?: Record<string, string>;
+    /**
+     * `@supports` query strings that wrap the generated rule
+     * (e.g. `['(display: grid)']`).
+     *
+     * An empty array means no `@supports` wrapper is emitted.
+     */
+    supportsQueries: string[];
+    /**
+     * Optional selector template that wraps the generated class name in a
+     * more complex selector pattern. The `&` character is replaced with the
+     * generated `.className` at render time.
+     *
+     * Used for utilities like `spaceX`/`spaceY` (child combinator selectors),
+     * `group-*` / `peer-*` modifiers, and `rtl`/`ltr` direction modifiers.
+     *
+     * @example
+     * ```ts
+     * // spaceX uses: '& > :not([hidden]) ~ :not([hidden])'
+     * // group-hover uses: '.group:hover &'
+     * ```
+     */
+    selectorTemplate?: string;
+}
+/**
+ * A function that accepts a design-token value and returns a {@link StyleRule}.
+ *
+ * Every spacing, color, typography, and layout helper (`p`, `bg`, `text`, ...)
+ * satisfies this signature. The `value` parameter is intentionally `any` so
+ * that individual utilities can narrow it to their own accepted types
+ * (e.g. `number | string | DynamicValue`).
+ *
+ * @param value - The design-token or raw CSS value to apply.
+ * @returns A {@link StyleRule} containing the appropriate CSS declarations.
+ *
+ * @example
+ * ```ts
+ * import type { Utility } from 'typewritingclass'
+ * import { p } from 'typewritingclass'
+ *
+ * // `p` satisfies the Utility signature:
+ * const myUtility: Utility = p
+ * const rule = myUtility(4)
+ * // CSS: padding: 1rem;
+ * ```
+ */
+type Utility = (value: any) => StyleRule;
+/**
+ * A function that transforms a {@link StyleRule} by wrapping it with a
+ * pseudo-class selector or a media query.
+ *
+ * Modifiers are composable -- you can chain them via {@link when} to build
+ * multi-condition rules (e.g. "on hover, at medium breakpoint").
+ *
+ * @param rule - The source {@link StyleRule} to transform.
+ * @returns A new {@link StyleRule} with additional selectors or media queries.
+ *
+ * @example
+ * ```ts
+ * import type { Modifier } from 'typewritingclass'
+ * import { hover, md } from 'typewritingclass'
+ *
+ * // `hover` and `md` are both Modifiers:
+ * const hoverMod: Modifier = hover
+ * const mdMod: Modifier = md
+ * ```
+ */
+type Modifier = (rule: StyleRule) => StyleRule;
+/**
+ * The return value of {@link dcx}, containing both a class string and an
+ * inline `style` object for dynamic CSS custom-property bindings.
+ *
+ * Use this when your styles include runtime-changeable values created with
+ * {@link dynamic}. The `className` goes on the element's class attribute, and
+ * `style` must be spread onto the element's inline style so the CSS custom
+ * properties are set.
+ *
+ * @example
+ * ```ts
+ * import { dcx, bg, dynamic } from 'typewritingclass'
+ *
+ * const color = dynamic('#ff0000')
+ * const result = dcx(bg(color))
+ * // result.className => "_a1b2c"
+ * // result.style     => { '--twc-d0': '#ff0000' }
+ *
+ * // In JSX:
+ * // <div className={result.className} style={result.style} />
+ * // CSS: .\_a1b2c { background-color: var(--twc-d0); }
+ * ```
+ */
+interface DynamicResult {
+    /** A space-separated string of generated CSS class names, ready for `className` or `class`. */
+    className: string;
+    /**
+     * An object of CSS custom property assignments to apply as inline styles.
+     *
+     * Keys are custom property names (e.g. `'--twc-d0'`), values are the
+     * current runtime values (e.g. `'#ff0000'`, `'1.5rem'`).
+     */
+    style: Record<string, string>;
+}
+
+export { type Brand as B, type CSSColor as C, type DynamicResult as D, type Modifier as M, type RadiusInput as R, type StyleRule as S, type Utility as U, type DynamicValue as a, type CSSFontWeight as b, type CSSLength as c, type CSSShadow as d, type ColorInput as e, type ShadowInput as f, type SizeInput as g, type SpacingInput as h, dynamic as i, isDynamic as j };

package/dist/typography-C8wipcCK.d.cts

@@ -0,0 +1,87 @@
+interface TextSize {
+    fontSize: string;
+    lineHeight: string;
+}
+declare const xs: TextSize;
+declare const sm: TextSize;
+declare const base: TextSize;
+declare const lg: TextSize;
+declare const xl: TextSize;
+declare const _2xl: TextSize;
+declare const _3xl: TextSize;
+declare const _4xl: TextSize;
+declare const _5xl: TextSize;
+declare const _6xl: TextSize;
+declare const _7xl: TextSize;
+declare const _8xl: TextSize;
+declare const _9xl: TextSize;
+declare const thin = "100";
+declare const extralight = "200";
+declare const light = "300";
+declare const normal = "400";
+declare const medium = "500";
+declare const semibold = "600";
+declare const bold = "700";
+declare const extrabold = "800";
+declare const black_ = "900";
+declare const fontFamilies: {
+    readonly sans: "ui-sans-serif, system-ui, sans-serif, \"Apple Color Emoji\", \"Segoe UI Emoji\", \"Segoe UI Symbol\", \"Noto Color Emoji\"";
+    readonly serif: "ui-serif, Georgia, Cambria, \"Times New Roman\", Times, serif";
+    readonly mono: "ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, \"Liberation Mono\", \"Courier New\", monospace";
+};
+declare const letterSpacings: {
+    readonly tighter: "-0.05em";
+    readonly tight: "-0.025em";
+    readonly normal: "0em";
+    readonly wide: "0.025em";
+    readonly wider: "0.05em";
+    readonly widest: "0.1em";
+};
+declare const lineHeights: {
+    readonly none: "1";
+    readonly tight: "1.25";
+    readonly snug: "1.375";
+    readonly normal: "1.5";
+    readonly relaxed: "1.625";
+    readonly loose: "2";
+    readonly '3': ".75rem";
+    readonly '4': "1rem";
+    readonly '5': "1.25rem";
+    readonly '6': "1.5rem";
+    readonly '7': "1.75rem";
+    readonly '8': "2rem";
+    readonly '9': "2.25rem";
+    readonly '10': "2.5rem";
+};
+
+type typography_TextSize = TextSize;
+declare const typography__2xl: typeof _2xl;
+declare const typography__3xl: typeof _3xl;
+declare const typography__4xl: typeof _4xl;
+declare const typography__5xl: typeof _5xl;
+declare const typography__6xl: typeof _6xl;
+declare const typography__7xl: typeof _7xl;
+declare const typography__8xl: typeof _8xl;
+declare const typography__9xl: typeof _9xl;
+declare const typography_base: typeof base;
+declare const typography_black_: typeof black_;
+declare const typography_bold: typeof bold;
+declare const typography_extrabold: typeof extrabold;
+declare const typography_extralight: typeof extralight;
+declare const typography_fontFamilies: typeof fontFamilies;
+declare const typography_letterSpacings: typeof letterSpacings;
+declare const typography_lg: typeof lg;
+declare const typography_light: typeof light;
+declare const typography_lineHeights: typeof lineHeights;
+declare const typography_medium: typeof medium;
+declare const typography_normal: typeof normal;
+declare const typography_semibold: typeof semibold;
+declare const typography_sm: typeof sm;
+declare const typography_thin: typeof thin;
+declare const typography_xl: typeof xl;
+declare const typography_xs: typeof xs;
+declare namespace typography {
+  export { type typography_TextSize as TextSize, typography__2xl as _2xl, typography__3xl as _3xl, typography__4xl as _4xl, typography__5xl as _5xl, typography__6xl as _6xl, typography__7xl as _7xl, typography__8xl as _8xl, typography__9xl as _9xl, typography_base as base, typography_black_ as black_, typography_bold as bold, typography_extrabold as extrabold, typography_extralight as extralight, typography_fontFamilies as fontFamilies, typography_letterSpacings as letterSpacings, typography_lg as lg, typography_light as light, typography_lineHeights as lineHeights, typography_medium as medium, typography_normal as normal, typography_semibold as semibold, typography_sm as sm, typography_thin as thin, typography_xl as xl, typography_xs as xs };
+}
+
+export { type TextSize as T, _2xl as _, _3xl as a, _4xl as b, _5xl as c, _6xl as d, _7xl as e, _8xl as f, _9xl as g, base as h, black_ as i, bold as j, extrabold as k, extralight as l, fontFamilies as m, letterSpacings as n, lg as o, light as p, lineHeights as q, medium as r, normal as s, typography as t, semibold as u, sm as v, thin as w, xl as x, xs as y };

package/dist/typography-C8wipcCK.d.ts

@@ -0,0 +1,87 @@
+interface TextSize {
+    fontSize: string;
+    lineHeight: string;
+}
+declare const xs: TextSize;
+declare const sm: TextSize;
+declare const base: TextSize;
+declare const lg: TextSize;
+declare const xl: TextSize;
+declare const _2xl: TextSize;
+declare const _3xl: TextSize;
+declare const _4xl: TextSize;
+declare const _5xl: TextSize;
+declare const _6xl: TextSize;
+declare const _7xl: TextSize;
+declare const _8xl: TextSize;
+declare const _9xl: TextSize;
+declare const thin = "100";
+declare const extralight = "200";
+declare const light = "300";
+declare const normal = "400";
+declare const medium = "500";
+declare const semibold = "600";
+declare const bold = "700";
+declare const extrabold = "800";
+declare const black_ = "900";
+declare const fontFamilies: {
+    readonly sans: "ui-sans-serif, system-ui, sans-serif, \"Apple Color Emoji\", \"Segoe UI Emoji\", \"Segoe UI Symbol\", \"Noto Color Emoji\"";
+    readonly serif: "ui-serif, Georgia, Cambria, \"Times New Roman\", Times, serif";
+    readonly mono: "ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, \"Liberation Mono\", \"Courier New\", monospace";
+};
+declare const letterSpacings: {
+    readonly tighter: "-0.05em";
+    readonly tight: "-0.025em";
+    readonly normal: "0em";
+    readonly wide: "0.025em";
+    readonly wider: "0.05em";
+    readonly widest: "0.1em";
+};
+declare const lineHeights: {
+    readonly none: "1";
+    readonly tight: "1.25";
+    readonly snug: "1.375";
+    readonly normal: "1.5";
+    readonly relaxed: "1.625";
+    readonly loose: "2";
+    readonly '3': ".75rem";
+    readonly '4': "1rem";
+    readonly '5': "1.25rem";
+    readonly '6': "1.5rem";
+    readonly '7': "1.75rem";
+    readonly '8': "2rem";
+    readonly '9': "2.25rem";
+    readonly '10': "2.5rem";
+};
+
+type typography_TextSize = TextSize;
+declare const typography__2xl: typeof _2xl;
+declare const typography__3xl: typeof _3xl;
+declare const typography__4xl: typeof _4xl;
+declare const typography__5xl: typeof _5xl;
+declare const typography__6xl: typeof _6xl;
+declare const typography__7xl: typeof _7xl;
+declare const typography__8xl: typeof _8xl;
+declare const typography__9xl: typeof _9xl;
+declare const typography_base: typeof base;
+declare const typography_black_: typeof black_;
+declare const typography_bold: typeof bold;
+declare const typography_extrabold: typeof extrabold;
+declare const typography_extralight: typeof extralight;
+declare const typography_fontFamilies: typeof fontFamilies;
+declare const typography_letterSpacings: typeof letterSpacings;
+declare const typography_lg: typeof lg;
+declare const typography_light: typeof light;
+declare const typography_lineHeights: typeof lineHeights;
+declare const typography_medium: typeof medium;
+declare const typography_normal: typeof normal;
+declare const typography_semibold: typeof semibold;
+declare const typography_sm: typeof sm;
+declare const typography_thin: typeof thin;
+declare const typography_xl: typeof xl;
+declare const typography_xs: typeof xs;
+declare namespace typography {
+  export { type typography_TextSize as TextSize, typography__2xl as _2xl, typography__3xl as _3xl, typography__4xl as _4xl, typography__5xl as _5xl, typography__6xl as _6xl, typography__7xl as _7xl, typography__8xl as _8xl, typography__9xl as _9xl, typography_base as base, typography_black_ as black_, typography_bold as bold, typography_extrabold as extrabold, typography_extralight as extralight, typography_fontFamilies as fontFamilies, typography_letterSpacings as letterSpacings, typography_lg as lg, typography_light as light, typography_lineHeights as lineHeights, typography_medium as medium, typography_normal as normal, typography_semibold as semibold, typography_sm as sm, typography_thin as thin, typography_xl as xl, typography_xs as xs };
+}
+
+export { type TextSize as T, _2xl as _, _3xl as a, _4xl as b, _5xl as c, _6xl as d, _7xl as e, _8xl as f, _9xl as g, base as h, black_ as i, bold as j, extrabold as k, extralight as l, fontFamilies as m, letterSpacings as n, lg as o, light as p, lineHeights as q, medium as r, normal as s, typography as t, semibold as u, sm as v, thin as w, xl as x, xs as y };