praxis-kit 0.1.0

package/dist/guards/index.d.ts

@@ -0,0 +1,78 @@
+import "clsx";
+import "../_shared/diagnostics.js";
+import "type-fest";
+//#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/foundation/src/type-guards.d.ts
+export declare function isString(value: unknown): value is string;
+export declare function isObject(value: unknown, excludeArrays: true): value is AnyRecord;
+export declare function isObject(value: unknown, excludeArrays?: false): value is object;
+//#endregion
+//#region ../../lib/primitive/src/guards/children/component-id.d.ts
+/**
+ * Well-known Symbol stamped onto every component created by praxis-kit factories.
+ * Stores the factory's defaultTag — the tag that renders when no `as` prop is given.
+ * HOC wrappers must propagate it: `Wrapped[COMPONENT_DEFAULT_TAG] = Original[COMPONENT_DEFAULT_TAG]`.
+ */
+export declare const COMPONENT_DEFAULT_TAG: unique symbol;
+/**
+ * Stamps `COMPONENT_DEFAULT_TAG` onto a component function/object, so `isTag()`
+ * (and every built-in/custom `enforcement.children` rule built on it) resolves it
+ * to `tag` — the same recognition a component created via `createContractComponent`
+ * gets automatically. A transparent wrapper around a praxis-kit component (added
+ * purely to narrow prop types, for example) is a *different* function object with
+ * no `COMPONENT_DEFAULT_TAG` of its own, so without this it silently stops being
+ * recognized as a valid child by every parent contract. Returns `component` for
+ * call-site chaining, e.g. `export const Wrapped = markComponentTag(WrapperFn, 'source')`.
+ */
+export declare function markComponentTag<T extends object>(component: T, tag: string): T;
+/** Reads `COMPONENT_DEFAULT_TAG` off a component function/object, if present. */
+export declare function getComponentDefaultTag(component: unknown): string | undefined;
+//#endregion
+//#region ../../lib/primitive/src/guards/children/is-tag.d.ts
+/**
+ * Resolves the effective HTML tag for a vnode:
+ *   - native element: returns its type string directly
+ *   - praxis-kit component: resolves `as ?? defaultTag`, mirroring render-time logic
+ *   - anything else: returns undefined
+ */
+export declare function getTag(child: unknown): string | undefined;
+/**
+ * Checks whether a vnode resolves to one of the given intrinsic tag names.
+ * Matches native elements directly, and praxis-kit components by resolving
+ * `as ?? defaultTag` — the same logic used at render time.
+ *
+ * Two call forms are supported:
+ *   isTag('img')(child)        — curried, composable with Array#filter
+ *   isTag(child, 'img')        — direct, reads naturally in if-blocks
+ */
+type TagChild = {
+  type: unknown;
+};
+export declare function isTag(tag: string, ...tags: readonly string[]): (child: unknown) => child is TagChild;
+export declare function isTag(child: unknown, tag: string, ...tags: readonly string[]): boolean;
+/**
+ * A vnode (or text node) that qualifies as flow content: text nodes
+ * (string/number) always qualify, and elements/components qualify unless
+ * their resolved tag is blocked — see `isFlowContent`.
+ */
+type FlowContentChild = string | number | TagChild;
+/**
+ * Checks whether a vnode is flow content per the HTML content model: text nodes
+ * (string/number) always qualify, and elements/components qualify unless their
+ * resolved tag is in the blocked set.
+ *
+ * Returns a type guard (not a plain boolean predicate) so it can be used
+ * directly as a `ChildRuleInput.match`, which requires the narrowed type.
+ */
+export declare function isFlowContent(...blockedTags: readonly string[]): (child: unknown) => child is FlowContentChild;
+//#endregion
+export type { FlowContentChild, TagChild };

package/dist/guards/index.js

@@ -0,0 +1,118 @@
+//#region ../../lib/foundation/src/type-guards.ts
+function isString(value) {
+	return typeof value === "string";
+}
+function isNumber(value) {
+	return typeof value === "number";
+}
+function isFunction(value) {
+	return typeof value === "function";
+}
+function isObject(value, excludeArrays = false) {
+	if (value === null || typeof value !== "object") return false;
+	return excludeArrays ? !Array.isArray(value) : true;
+}
+//#endregion
+//#region ../../lib/primitive/src/guards/children/component-id.ts
+/**
+* Well-known Symbol stamped onto every component created by praxis-kit factories.
+* Stores the factory's defaultTag — the tag that renders when no `as` prop is given.
+* HOC wrappers must propagate it: `Wrapped[COMPONENT_DEFAULT_TAG] = Original[COMPONENT_DEFAULT_TAG]`.
+*/
+const COMPONENT_DEFAULT_TAG = Symbol.for("praxis.component-default-tag");
+function isMarkable(value) {
+	return isFunction(value) || isObject(value);
+}
+/**
+* Stamps one or more `WithComponentId` keys onto a component function/object as
+* non-writable, non-enumerable properties — accidental plain-assignment overwrite
+* (`Wrapped[COMPONENT_DEFAULT_TAG] = 'div'` clobbering an already-stamped value) is
+* rejected, but `configurable: true` keeps it re-stampable through this same helper
+* (e.g. a component factory re-running in dev/HMR), rather than throwing outright.
+* Single choke point every `mark*` helper below funnels through, so future metadata
+* keys only need a property list here, not a new stamping mechanism.
+*/
+function defineComponentMetadata(component, metadata) {
+	for (const key of Object.getOwnPropertySymbols(metadata)) Object.defineProperty(component, key, {
+		value: metadata[key],
+		writable: false,
+		configurable: true,
+		enumerable: false
+	});
+	return component;
+}
+/**
+* Stamps `COMPONENT_DEFAULT_TAG` onto a component function/object, so `isTag()`
+* (and every built-in/custom `enforcement.children` rule built on it) resolves it
+* to `tag` — the same recognition a component created via `createContractComponent`
+* gets automatically. A transparent wrapper around a praxis-kit component (added
+* purely to narrow prop types, for example) is a *different* function object with
+* no `COMPONENT_DEFAULT_TAG` of its own, so without this it silently stops being
+* recognized as a valid child by every parent contract. Returns `component` for
+* call-site chaining, e.g. `export const Wrapped = markComponentTag(WrapperFn, 'source')`.
+*/
+function markComponentTag(component, tag) {
+	return defineComponentMetadata(component, { [COMPONENT_DEFAULT_TAG]: tag });
+}
+/** Reads `COMPONENT_DEFAULT_TAG` off a component function/object, if present. */
+function getComponentDefaultTag(component) {
+	if (!isMarkable(component)) return void 0;
+	const tag = component[COMPONENT_DEFAULT_TAG];
+	return typeof tag === "string" ? tag : void 0;
+}
+//#endregion
+//#region ../../lib/primitive/src/guards/children/is-tag.ts
+function getAsProp(child) {
+	if (!isObject(child) || !("props" in child)) return void 0;
+	const { props } = child;
+	if (!isObject(props)) return void 0;
+	const as = Reflect.get(props, "as");
+	return isString(as) && as !== "" ? as : void 0;
+}
+/**
+* Resolves the effective HTML tag for a vnode:
+*   - native element: returns its type string directly
+*   - praxis-kit component: resolves `as ?? defaultTag`, mirroring render-time logic
+*   - anything else: returns undefined
+*/
+function getTag(child) {
+	if (!isObject(child) || !("type" in child)) return void 0;
+	const { type: t } = child;
+	if (isString(t)) return t;
+	if (typeof t === "function" || isObject(t)) {
+		const defaultTag = Reflect.get(t, COMPONENT_DEFAULT_TAG);
+		if (!isString(defaultTag)) return void 0;
+		return getAsProp(child) ?? defaultTag;
+	}
+}
+function isTag(...args) {
+	if (isString(args[0])) {
+		const set = new Set(args);
+		return (child) => {
+			const tag = getTag(child);
+			return tag !== void 0 && set.has(tag);
+		};
+	}
+	const [child, ...tags] = args;
+	const set = new Set(tags);
+	const tag = getTag(child);
+	return tag !== void 0 && set.has(tag);
+}
+/**
+* Checks whether a vnode is flow content per the HTML content model: text nodes
+* (string/number) always qualify, and elements/components qualify unless their
+* resolved tag is in the blocked set.
+*
+* Returns a type guard (not a plain boolean predicate) so it can be used
+* directly as a `ChildRuleInput.match`, which requires the narrowed type.
+*/
+function isFlowContent(...blockedTags) {
+	const set = new Set(blockedTags);
+	return (child) => {
+		if (isString(child) || isNumber(child)) return true;
+		const tag = getTag(child);
+		return tag === void 0 || !set.has(tag);
+	};
+}
+//#endregion
+export { COMPONENT_DEFAULT_TAG, getComponentDefaultTag, getTag, isFlowContent, isObject, isString, isTag, markComponentTag };

package/dist/html/index.d.ts

@@ -0,0 +1,151 @@
+import "clsx";
+import { DiagnosticCode, DiagnosticInput } from "../_shared/diagnostics.js";
+import { ReadonlyDeep } from "type-fest";
+//#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/intrinsic-tag.d.ts
+type IntrinsicTag = keyof HTMLElementTagNameMap;
+//#endregion
+//#region ../../lib/primitive/src/constants/aria/known-aria-roles.d.ts
+declare const KNOWN_ARIA_ROLES: readonly ["alert", "alertdialog", "application", "article", "banner", "blockquote", "button", "caption", "cell", "checkbox", "code", "columnheader", "combobox", "complementary", "contentinfo", "definition", "deletion", "dialog", "document", "emphasis", "feed", "figure", "form", "generic", "grid", "gridcell", "group", "heading", "img", "insertion", "link", "list", "listbox", "listitem", "log", "main", "marquee", "math", "menu", "menubar", "menuitem", "menuitemcheckbox", "menuitemradio", "meter", "navigation", "none", "note", "option", "paragraph", "presentation", "progressbar", "radio", "radiogroup", "region", "row", "rowgroup", "rowheader", "scrollbar", "search", "searchbox", "separator", "slider", "spinbutton", "status", "strong", "subscript", "superscript", "switch", "tab", "table", "tablist", "tabpanel", "term", "textbox", "time", "timer", "toolbar", "tooltip", "tree", "treegrid", "treeitem"];
+type KnownAriaRole = (typeof KNOWN_ARIA_ROLES)[number];
+//#endregion
+//#region ../../lib/primitive/src/types/primitives/index.d.ts
+type AriaRole = KnownAriaRole | (string & {});
+type IntrinsicProps = AnyRecord & {
+  role?: AriaRole;
+};
+//#endregion
+//#region ../../lib/primitive/src/types/validation/valid-result.d.ts
+type ValidResult = {
+  valid: true;
+};
+//#endregion
+//#region ../../lib/primitive/src/types/aria-rule/aria-context.d.ts
+type AriaContext = {
+  /**
+   * The intrinsic HTML tag being evaluated.
+   */
+  readonly tag: IntrinsicTag;
+  /**
+   * The implicit ARIA role associated with the intrinsic tag.
+   */
+  readonly implicitRole: AriaRole | undefined;
+  /**
+   * The effective ARIA role after considering the element's explicit
+   * `role` attribute or component-provided role.
+   */
+  readonly effectiveRole: string | undefined;
+  /**
+   * The component's props available to the ARIA policy engine.
+   */
+  readonly props: ReadonlyDeep<IntrinsicProps>;
+  /**
+   * Variant prop names declared by the component.
+   *
+   * The adapter uses these names to determine which props are intercepted
+   * before reaching the DOM. A rule asserting a fact about a real HTML
+   * attribute should therefore treat a key present here as a component
+   * variant rather than a DOM attribute.
+   *
+   * An empty set indicates no variant props are declared — the case for
+   * evaluations with no factory context, such as `AriaPolicyEngine.evaluate`.
+   */
+  readonly variantKeys: ReadonlySet<string>;
+};
+//#endregion
+//#region ../../lib/primitive/src/types/aria-rule/fix-kind.d.ts
+type RemoveAttributeFixKind = 'removeAttribute';
+type InjectLiveFixKind = 'injectLive';
+type FixKind = 'removeRole' | 'setRole' | 'normalizeRelevantAll' | RemoveAttributeFixKind | InjectLiveFixKind;
+//#endregion
+//#region ../../lib/primitive/src/types/aria-rule/aria-fix.d.ts
+type AriaFixResult = {
+  applied: false;
+  next: ReadonlyDeep<IntrinsicProps>;
+} | {
+  applied: true;
+  next: ReadonlyDeep<IntrinsicProps>;
+  previous: ReadonlyDeep<IntrinsicProps>;
+};
+type AriaFix = {
+  readonly kind: FixKind;
+  /** The attribute a `'removeAttribute'`/`'injectLive'` fix targets — always set for those
+   *  kinds, absent for kinds with no single-attribute target (`'removeRole'`, etc.). */
+  readonly attribute?: string;
+  readonly priority?: number;
+  readonly source?: string;
+  readonly apply: (context: AriaContext) => AriaFixResult;
+};
+//#endregion
+//#region ../../lib/primitive/src/types/aria-rule/severity.d.ts
+type Severity = 'error' | 'warning' | (string & {});
+//#endregion
+//#region ../../lib/primitive/src/types/aria-rule/aria-result.d.ts
+type AriaInvalidBase<M extends string = string> = {
+  valid: false;
+  severity: Severity;
+  message?: M;
+  attribute?: string;
+  diagnostic?: DiagnosticInput;
+};
+type AriaInvalidWithFix<M extends string = string> = AriaInvalidBase<M> & {
+  fixable: true;
+  fix: AriaFix;
+};
+type AriaInvalidWithoutFix<M extends string = string> = AriaInvalidBase<M> & {
+  fixable: false;
+};
+type AriaInvalidResult<M extends string = string> = AriaInvalidWithFix<M> | AriaInvalidWithoutFix<M>;
+type AriaResult = ValidResult | AriaInvalidResult;
+//#endregion
+//#region ../../lib/primitive/src/types/aria-rule/aria-rule.d.ts
+type AriaRule<C extends AriaContext = AriaContext> = ((context: C) => readonly AriaResult[]) & {
+  readonly readsProps?: readonly string[];
+  readonly tags?: readonly string[];
+};
+//#endregion
+//#region ../core/src/html/aria-rules.d.ts
+export declare const landmarkRoleRule: AriaRule;
+export declare function requireAccessibleName({ tag, props }: AriaContext): readonly AriaResult[];
+export declare const landmarkAccessibleNameRule: AriaRule;
+export declare const HTML_ARIA_RULES: readonly AriaRule[];
+//#endregion
+//#region ../core/src/html/role-restrictions.d.ts
+export declare const roleNotPermittedRule: AriaRule;
+//#endregion
+//#region ../core/src/html/anchor-rules.d.ts
+export declare const dangerousHrefRule: AriaRule;
+export declare const roleButtonWithHrefRule: AriaRule;
+export declare const ariaDisabledInertRule: AriaRule;
+export declare const ANCHOR_RULES: readonly AriaRule[];
+//#endregion
+//#region ../core/src/html/input-rules.d.ts
+export declare const supportedInputTypeRule: AriaRule;
+export declare const checkedRequiresCheckableTypeRule: AriaRule;
+export declare const multipleRequiresSupportedTypeRule: AriaRule;
+export declare const maxLengthRequiresTextTypeRule: AriaRule;
+export declare const minLengthRequiresTextTypeRule: AriaRule;
+export declare const patternRequiresTextTypeRule: AriaRule;
+export declare const minRequiresNumericTypeRule: AriaRule;
+export declare const maxRequiresNumericTypeRule: AriaRule;
+export declare const stepRequiresNumericTypeRule: AriaRule;
+export declare const acceptRequiresFileTypeRule: AriaRule;
+export declare const captureRequiresFileTypeRule: AriaRule;
+export declare const sizeRequiresTextTypeRule: AriaRule;
+export declare const altRequiresImageTypeRule: AriaRule;
+export declare const heightRequiresImageTypeRule: AriaRule;
+export declare const widthRequiresImageTypeRule: AriaRule;
+export declare const inputAccessibleNameRule: AriaRule;
+export declare const passwordAutocompleteRule: AriaRule;
+export declare const requiredReadOnlyConflictRule: AriaRule;
+export declare const INPUT_RULES: readonly AriaRule[];
+//#endregion