@greese/ui 0.0.0-stage → 1.0.0

package/dist/utilities.d.ts

@@ -0,0 +1,82 @@
+/**
+ * Utility classes: one declaration (or a small, named set) per class, built
+ * from the tokens, in `@layer greese.utilities` so they beat a component's own
+ * styles. Defined here, once; everything else is made from this table:
+ *
+ * - `dist/utilities.css`, the whole set (`@greese/ui/utilities.css`);
+ * - `generateUtilities({ used })` and `purgeUtilities({ content })`, which write
+ *   only the classes a project uses, found by scanning its source, so unused
+ *   CSS never ships (the `greese-utilities` command and the Vite plugin run it);
+ * - the docs' class tables.
+ *
+ * **Names.** `<property>-<value>`: the property's own name and the value's own
+ * keyword, so a class reads as the declaration it makes (`display-flex`,
+ * `text-center`, `justify-content-between`). Token-valued groups use
+ * the token's name (`p-4`, `bg-primary`, `radius-md`,
+ * `z-modal`). These abbreviations only, for the properties used most:
+ * `m` margin, `p` padding, `w` width, `h` height, `z` z-index, `bg`
+ * background-color, `pos` position, `vis` visibility, `flex-dir` flex-direction,
+ * `col`/`cols` for column/columns, `text` for text-align, `upper`/`lower` for
+ * uppercase/lowercase. Spacing takes a side: `t b l r` (physical), `x y` (the
+ * inline and block axes), `s e` (inline start and end, which follow the
+ * writing direction): `pt-3`, `mx-auto`, `ms-2`. A breakpoint or
+ * `hover` goes first: `md-display-flex`, `hover-opacity-75`.
+ * Type size and radius stay tokens and type variants (`text-lg`, `rounded-xl`
+ * have no equivalent here).
+ *
+ * Keep this file's imports to the token modules: the build runs it directly
+ * under Node's type stripping.
+ */
+type Declarations = Readonly<Record<string, string>>;
+export type UtilityGroup = 'spacing' | 'sizing' | 'layout' | 'flex' | 'grid' | 'typography' | 'border' | 'color' | 'effects';
+/** A class the set can write, with where it applies. */
+export interface UtilityClass {
+    /** The class name, variant included: `md-display-flex`. */
+    name: string;
+    group: UtilityGroup;
+    /** The class after the variant: `mt`, `display`. */
+    stem: string;
+    /** The value part (`4`, `flex`), or `''` for the stem alone. */
+    value: string;
+    /** `hover`, a breakpoint key, or none. */
+    variant?: string;
+    declarations: Declarations;
+}
+export interface UtilityOptions {
+    /** A prefix for every class (`g` gives `g-p-4`), if the project wants one. @default none */
+    prefix?: string;
+    /** Only these groups. @default all */
+    groups?: readonly UtilityGroup[];
+    /** Breakpoint keys and their min-widths in px: the build's. @default the library's */
+    breakpoints?: Readonly<Record<string, number>>;
+    /** Only classes with these names (purging); undefined writes them all. */
+    used?: ReadonlySet<string>;
+}
+/**
+ * Every class in the set, in the order they are written: plain, hover, then
+ * each breakpoint smallest first, so a larger screen's class beats a smaller
+ * one's at equal specificity (mobile first).
+ */
+export declare const utilityClasses: ({ prefix, groups, breakpoints, }?: UtilityOptions) => UtilityClass[];
+/**
+ * The CSS for the utilities: the layer order, then the classes in
+ * `@layer greese.utilities`. With `used`, only those classes (see
+ * `purgeUtilities`).
+ */
+export declare const generateUtilities: (options?: UtilityOptions) => string;
+/** Every token in some source text that could be a class name. */
+export declare const scanContent: (text: string) => Set<string>;
+export interface PurgeOptions extends Omit<UtilityOptions, 'used'> {
+    /** Source text to look for class names in: markup, components, templates. */
+    content: Iterable<string>;
+    /** Classes (or patterns) to keep even if the source never spells them out, such as ones built at run time. */
+    safelist?: ReadonlyArray<string | RegExp>;
+}
+/**
+ * Only the utilities a project uses. A class counts as used when its name
+ * appears anywhere in the content, as a whole word, so `class="p-4"`,
+ * `className={cx('p-4')}` and a name in a data file all count; one built from
+ * pieces (`` `p-${n}` ``) does not, and belongs in `safelist`.
+ */
+export declare const purgeUtilities: ({ content, safelist, ...options }: PurgeOptions) => string;
+export {};