praxis-kit 0.1.0

package/dist/tailwind/index.d.ts

@@ -0,0 +1,197 @@
+import "clsx";
+import { DiagnosticCode, Diagnostics } from "../_shared/diagnostics.js";
+import { RequireAtLeastOne, Simplify } from "type-fest";
+//#region ../../lib/tailwind/src/layout-keys.d.ts
+/**
+ * Canonical list of reserved layout prop names.
+ *
+ * This array is the single source of truth for every supported CSS `display`
+ * value exposed as a boolean prop. The `LayoutKey` type is derived directly
+ * from this list.
+ *
+ * To add a new display mode:
+ *   1. Add the display value here.
+ *   2. Register its layout family in `LAYOUT_FAMILY_MAP`.
+ *
+ * Prop names intentionally match the corresponding Tailwind/CSS display
+ * utilities, so no additional prop-to-class mapping is required.
+ */
+export declare const layoutKeys: readonly ["flex", "inline-flex", "grid", "inline-grid", "block", "inline-block", "inline", "hidden", "contents", "flow-root", "list-item", "table", "inline-table", "table-caption", "table-cell", "table-column", "table-column-group", "table-footer-group", "table-header-group", "table-row-group", "table-row"];
+//#endregion
+//#region ../../lib/foundation/src/string-map.d.ts
+/**
+ * A string-keyed object whose values are of type `T`.
+ */
+type StringMap<T = unknown> = Record<string, T>;
+/**
+ * A string-keyed object with values of unknown type.
+ */
+type AnyRecord = StringMap<unknown>;
+//#endregion
+//#region ../../lib/primitive/src/types/any-record.d.ts
+/**
+ * An object type with no named properties.
+ *
+ * Unlike `{}`, this excludes arbitrary properties during type operations while
+ * still satisfying `extends object`.
+ */
+type EmptyRecord = Record<never, never>;
+//#endregion
+//#region ../../lib/primitive/src/types/intrinsic-tag.d.ts
+type IntrinsicTag = keyof HTMLElementTagNameMap;
+//#endregion
+//#region ../../lib/primitive/src/types/primitives/index.d.ts
+type Booleanish = boolean | 'true' | 'false';
+type ClassName = string | string[];
+type NonEmptyArray<T> = [T, ...T[]];
+type Numberish = number | `${number}`;
+type Primitive = string | number | boolean;
+type TagMap = Partial<Record<IntrinsicTag | (string & {}), ClassName>>;
+//#endregion
+//#region ../../lib/primitive/src/types/variants/string-to-boolean.d.ts
+type StringToBoolean<T> = T extends 'true' | 'false' ? boolean : T;
+//#endregion
+//#region ../../lib/primitive/src/types/variants/variant-value.d.ts
+type VariantValue = string | string[];
+//#endregion
+//#region ../../lib/primitive/src/types/variants/variant-states.d.ts
+type VariantStates<K extends string = string> = Record<K, VariantValue>;
+//#endregion
+//#region ../../lib/primitive/src/types/variants/variant-map.d.ts
+type VariantMap<V extends string = string, K extends string = string> = Record<V, VariantStates<K>>;
+//#endregion
+//#region ../../lib/primitive/src/types/variants/variant-key.d.ts
+type VariantKey<V extends VariantMap, K extends keyof V> = StringToBoolean<keyof V[K] & string>;
+//#endregion
+//#region ../../lib/primitive/src/types/variants/variant-selection.d.ts
+/**
+ * A partial selection of variant states authored at factory definition time.
+ *
+ * Uses `keyof V[K]` directly (not `VariantKey`) so TypeScript can eagerly
+ * resolve the union at constraint-check time without deferred conditional types.
+ */
+type VariantSelection<V extends VariantMap> = { [K in keyof V]?: keyof V[K]; };
+//#endregion
+//#region ../../lib/primitive/src/types/variants/default-variants.d.ts
+type NormalizedVariantValue<K extends string> = string extends K ? Primitive : K extends 'true' | 'false' ? Booleanish : K extends `${number}` ? Numberish : K;
+type DefaultVariants<V extends VariantMap> = { [K in keyof V]?: NormalizedVariantValue<keyof V[K] & string>; };
+//#endregion
+//#region ../../lib/primitive/src/types/variants/recipe-target.d.ts
+type RecipeTarget<TVariants extends VariantMap = VariantMap> = VariantSelection<TVariants>;
+//#endregion
+//#region ../../lib/primitive/src/types/variants/compound/compound-variant.d.ts
+type RequireAtLeastOneIfNotEmpty<T> = keyof T extends never ? EmptyRecord : RequireAtLeastOne<T>;
+type CompoundVariantConditionValue<V extends VariantMap, K extends keyof V> = VariantKey<V, K> | NonEmptyArray<VariantKey<V, K>>;
+type CompoundVariantConditions<V extends VariantMap> = Simplify<{ [K in keyof V]: CompoundVariantConditionValue<V, K>; }>;
+type CompoundVariantRequiredConditions<V extends VariantMap> = RequireAtLeastOneIfNotEmpty<CompoundVariantConditions<V>>;
+type CompoundVariantBase<V extends VariantMap> = keyof V extends never ? EmptyRecord : CompoundVariantRequiredConditions<V>;
+type CompoundVariant<V extends VariantMap> = CompoundVariantBase<V> & {
+  class: VariantValue;
+};
+//#endregion
+//#region ../../lib/primitive/src/types/variants/compound/cva-compounds.d.ts
+interface CVACompounds<V extends VariantMap> {
+  compoundVariants?: readonly CompoundVariant<V>[];
+}
+//#endregion
+//#region ../../lib/primitive/src/types/variants/compound/cva-defaults.d.ts
+interface CVADefaults<V extends VariantMap> {
+  defaultVariants?: DefaultVariants<V>;
+}
+//#endregion
+//#region ../../lib/primitive/src/types/variants/compound/cva-variants.d.ts
+interface CVAVariants<V extends VariantMap> {
+  variants?: V;
+}
+//#endregion
+//#region ../../lib/primitive/src/types/pipeline/base-class-options.d.ts
+interface BaseClassOptions {
+  baseClassName?: ClassName;
+}
+//#endregion
+//#region ../../lib/primitive/src/types/pipeline/class-pipeline-fn.d.ts
+type ClassPipelineFn = (tag: unknown, props: AnyRecord, className?: ClassName, recipe?: string) => string | undefined;
+//#endregion
+//#region ../../lib/primitive/src/types/pipeline/recipe-options.d.ts
+interface RecipeOptions<TVariants extends VariantMap = VariantMap> {
+  recipeMap?: StringMap<RecipeTarget<TVariants>>;
+}
+//#endregion
+//#region ../../lib/primitive/src/types/pipeline/tag-map-options.d.ts
+interface TagMapOptions {
+  tagMap?: TagMap;
+}
+//#endregion
+//#region ../../lib/primitive/src/types/pipeline/composition-options.d.ts
+type CompositionOptions<TVariants extends VariantMap = VariantMap> = Simplify<TagMapOptions & RecipeOptions<TVariants>>;
+//#endregion
+//#region ../../lib/primitive/src/types/pipeline/cva-system-options.d.ts
+type CVASystemOptions<TVariants extends VariantMap = VariantMap> = Simplify<CVAVariants<TVariants> & CVADefaults<TVariants> & CVACompounds<TVariants>>;
+//#endregion
+//#region ../../lib/primitive/src/types/pipeline/style-options.d.ts
+type StyleOptions<TVariants extends VariantMap = VariantMap> = Simplify<BaseClassOptions & CVASystemOptions<TVariants>>;
+//#endregion
+//#region ../../lib/primitive/src/types/pipeline/class-pipeline-options.d.ts
+type ClassPipelineOptions<TVariants extends VariantMap = VariantMap> = Simplify<StyleOptions<TVariants> & CompositionOptions<TVariants>>;
+//#endregion
+//#region ../../lib/primitive/src/types/class/owned-prop-keys.d.ts
+type OwnedPropKeys = ReadonlySet<string>;
+//#endregion
+//#region ../../lib/primitive/src/types/class/class-plugin.d.ts
+type ClassPlugin<TProps extends AnyRecord = EmptyRecord> = Readonly<{
+  pipeline: ClassPipelineFn;
+  ownedKeys?: OwnedPropKeys;
+  readonly _pluginProps?: TProps;
+}>;
+//#endregion
+//#region ../../lib/tailwind/src/types/layout.d.ts
+type TupleValues<T extends readonly unknown[]> = T[number];
+type LayoutKey<T extends readonly string[]> = TupleValues<T>;
+type ResolvedLayout<T extends readonly string[]> = LayoutKey<T> | 'none';
+type ExclusiveTrueProp<K extends PropertyKey> = { [P in K]: Simplify<Record<P, true> & Partial<Record<Exclude<K, P>, never>>>; }[K];
+/**
+ * Mutually exclusive layout shorthand props.
+ *
+ * Exactly one layout prop may be `true`, or none at all. Multiple `true`
+ * props produce a compile-time error. If invalid props reach runtime, the
+ * resolver warns and uses the first declared layout.
+ */
+type LayoutProps<T extends readonly string[]> = ExclusiveTrueProp<LayoutKey<T>> | Partial<Record<LayoutKey<T>, never>>;
+//#endregion
+//#region ../../lib/tailwind/src/create-tailwind-pipeline.d.ts
+/**
+ * Layout-aware class pipeline for Tailwind CSS utility class strings.
+ *
+ * This is a `ClassPluginFactory` — the runtime calls it with the component's
+ * resolved pipeline options and strict mode. Do NOT call it yourself; pass the
+ * function reference as `styling.plugin` and let the runtime invoke it.
+ *
+ * @example
+ * ```ts
+ * // CORRECT — pass the reference; the runtime calls it
+ * createContractComponent({
+ *   tag: 'div',
+ *   styling: {
+ *     base: 'items-center',
+ *     plugin: createTailwindPipeline,
+ *   },
+ * })
+ *
+ * // WRONG — calling it manually produces a ClassPlugin where a ClassPluginFactory is expected
+ * createContractComponent({
+ *   tag: 'div',
+ *   styling: {
+ *     plugin: createTailwindPipeline({ base: 'items-center' }, false),
+ *   },
+ * })
+ * ```
+ *
+ * With the plugin active, pass any display prop (`flex`, `inline-flex`, `grid`,
+ * `inline-grid`, `block`, `hidden`, etc.) as a boolean to control the display
+ * mode. The pipeline injects the display class and strips conflicting utilities:
+ * flex-family modes strip `grid-*`; grid-family modes strip `flex-*`; all other
+ * display values (and no prop) strip both `flex-*` and `grid-*`.
+ */
+export declare function createTailwindPipeline<V extends VariantMap = VariantMap>(options: ClassPipelineOptions<V>, diagnostics: Diagnostics): ClassPlugin<LayoutProps<typeof layoutKeys>>;
+//#endregion
+export type { LayoutKey, LayoutProps, ResolvedLayout };