@pantoken/components 0.1.0

package/dist/index.d.mts

@@ -0,0 +1,363 @@
+//#region src/lib/helpers.d.ts
+/**
+ * Shared primitives for the component builders: the class-prefix namespace helper, the standalone-sheet
+ * `wrap` header, the masked-glyph constants, and the spacing scales. These carry no per-record content —
+ * every `src/{components,utilities,rules,declarations}` module imports what it needs from here.
+ *
+ * @module
+ */
+/** The default class prefix (`instui` → `.instui-button`). */
+declare const DEFAULT_PREFIX = "instui";
+/** Options common to every builder. */
+interface ComponentOptions {
+  /**
+   * The class prefix. A truthy string namespaces every class (`"instui"` → `.instui-button`); any
+   * falsy value (`null`, `undefined`, `""`, or omitting the option) drops the prefix entirely
+   * (`.button`), so you can author `class="heading -h1"`. The stylesheets shipped by this package are
+   * built with `"instui"`.
+   */
+  prefix?: string | null;
+}
+//#endregion
+//#region src/rules/prose.d.ts
+/** Options for {@link proseCss}. */
+interface ProseOptions {
+  /** The content-root selector the rules attach to (default `".pantoken-prose"`). */
+  scope?: string;
+}
+/**
+ * Build the InstUI-look prose stylesheet, scoped to `options.scope` (default `.pantoken-prose`).
+ *
+ * @param options - {@link ProseOptions}.
+ * @returns The CSS string.
+ *
+ * @demo self:prose
+ */
+declare function proseCss(options?: ProseOptions): string;
+//#endregion
+//#region src/declarations/elevation.d.ts
+/**
+ * The `--instui-elevation-*` shadow scale. Helpers only — NOT a documented record and not in any
+ * registry: `componentsCss()` leads its sheet with `elevationCss()` so the shadows components
+ * reference (modal, alert, menu) resolve from `components.css` alone.
+ *
+ * @module
+ */
+/**
+ * Every elevation level and alias emitted as `--instui-elevation-<name>` (`resting`, `above`,
+ * `topmost`, `depth1`–`depth3`, `card`, `cardHover`). Derived from the geometry + alias maps.
+ */
+declare const ELEVATION_NAMES: readonly string[];
+/**
+ * The `--instui-elevation-*` name/value pairs (each a multi-layer `box-shadow`). Values reference the
+ * themed drop-shadow colour tokens, so they adapt per theme wherever a token sheet is loaded.
+ *
+ * @returns One `[customProperty, value]` pair per level and alias.
+ */
+declare function elevationDeclarations(): [name: string, value: string][];
+/**
+ * Build the elevation token block: `<selector> { --instui-elevation-*: … }`. Shipped inside
+ * `components.css` (so shadows are intrinsic — no plugin, no extra import), and reusable by other
+ * layered outputs (e.g. the Pendo renderer) via the `selector` option.
+ *
+ * @param options - `selector` — the rule selector (default `:root`).
+ * @returns The CSS string.
+ *
+ * @example
+ * ```ts
+ * import { elevationCss } from "@pantoken/components";
+ *
+ * elevationCss(); // ":root { --instui-elevation-resting: …; --instui-elevation-above: …; … }"
+ * ```
+ *
+ * @demo self:elevation
+ */
+declare function elevationCss(options?: {
+  selector?: string;
+}): string;
+//#endregion
+//#region src/declarations/focus.d.ts
+/** The elements the ring applies to by default (the common interactive/focusable elements). */
+declare const FOCUSABLE_SELECTOR = "a, button, input, select, textarea, summary, [tabindex]";
+/**
+ * The `--instui-focus-outline-*` name/value pairs the ring rules read. Colour/width/offset reference
+ * the themed shared focus tokens; the transition, line style, and inset are constants.
+ *
+ * @returns One `[customProperty, value]` pair per focus-ring variable.
+ */
+declare function focusOutlineDeclarations(): [name: string, value: string][];
+/**
+ * The focus-ring rules for a given focusable selector: a transparent resting ring that transitions in
+ * on `:focus-visible`, plus the `-focus-color-*` / `-focus-position-inset` / `-focus-within` /
+ * `-without-focus-animation` modifiers. All `:where()`-wrapped, so zero-specificity.
+ *
+ * @param selector - The focusable selector the base ring applies to (default {@link FOCUSABLE_SELECTOR}).
+ * @returns The CSS rules string.
+ */
+declare function focusOutlineRules(selector?: string): string;
+/**
+ * Build the focus-outline block: the `--instui-focus-outline-*` token defs plus the ring rules.
+ * Baked into `base.css` (so focusables get the ring out of the box), and reusable by other layered
+ * outputs (e.g. the Pendo renderer) via the `selector`/`tokenSelector` options.
+ *
+ * @param options - `selector` — the focusable selector; `tokenSelector` — where the token defs land
+ *   (default `:where(:root)`).
+ * @returns The CSS string.
+ *
+ * @demo self:focus-outline
+ */
+declare function focusOutlineCss(options?: {
+  selector?: string;
+  tokenSelector?: string;
+}): string;
+//#endregion
+//#region src/components/button.d.ts
+declare const buttonCss: (this: void, options?: ComponentOptions) => string;
+//#endregion
+//#region src/components/alert.d.ts
+declare const alertCss: (this: void, options?: ComponentOptions) => string;
+//#endregion
+//#region src/components/badge.d.ts
+declare const badgeCss: (this: void, options?: ComponentOptions) => string;
+//#endregion
+//#region src/components/pill.d.ts
+declare const pillCss: (this: void, options?: ComponentOptions) => string;
+//#endregion
+//#region src/components/tag.d.ts
+declare const tagCss: (this: void, options?: ComponentOptions) => string;
+//#endregion
+//#region src/components/avatar.d.ts
+declare const avatarCss: (this: void, options?: ComponentOptions) => string;
+//#endregion
+//#region src/components/tabs.d.ts
+declare const tabsCss: (this: void, options?: ComponentOptions) => string;
+//#endregion
+//#region src/components/metric.d.ts
+declare const metricCss: (this: void, options?: ComponentOptions) => string;
+//#endregion
+//#region src/components/img.d.ts
+declare const imgCss: (this: void, options?: ComponentOptions) => string;
+//#endregion
+//#region src/components/byline.d.ts
+declare const bylineCss: (this: void, options?: ComponentOptions) => string;
+//#endregion
+//#region src/components/table.d.ts
+declare const tableCss: (this: void, options?: ComponentOptions) => string;
+//#endregion
+//#region src/components/link.d.ts
+declare const linkCss: (this: void, options?: ComponentOptions) => string;
+//#endregion
+//#region src/components/list.d.ts
+declare const listCss: (this: void, options?: ComponentOptions) => string;
+//#endregion
+//#region src/components/checkbox.d.ts
+declare const checkboxCss: (this: void, options?: ComponentOptions) => string;
+//#endregion
+//#region src/components/radio.d.ts
+declare const radioCss: (this: void, options?: ComponentOptions) => string;
+//#endregion
+//#region src/components/spinner.d.ts
+declare const spinnerCss: (this: void, options?: ComponentOptions) => string;
+//#endregion
+//#region src/components/progress.d.ts
+declare const progressCss: (this: void, options?: ComponentOptions) => string;
+//#endregion
+//#region src/components/menu.d.ts
+declare const menuCss: (this: void, options?: ComponentOptions) => string;
+//#endregion
+//#region src/components/modal.d.ts
+declare const modalCss: (this: void, options?: ComponentOptions) => string;
+//#endregion
+//#region src/components/breadcrumb.d.ts
+declare const breadcrumbCss: (this: void, options?: ComponentOptions) => string;
+//#endregion
+//#region src/components/billboard.d.ts
+declare const billboardCss: (this: void, options?: ComponentOptions) => string;
+//#endregion
+//#region src/components/rating.d.ts
+declare const ratingCss: (this: void, options?: ComponentOptions) => string;
+//#endregion
+//#region src/components/toggle-group.d.ts
+declare const toggleGroupCss: (this: void, options?: ComponentOptions) => string;
+//#endregion
+//#region src/components/context-view.d.ts
+declare const contextViewCss: (this: void, options?: ComponentOptions) => string;
+//#endregion
+//#region src/components/progress-circle.d.ts
+declare const progressCircleCss: (this: void, options?: ComponentOptions) => string;
+//#endregion
+//#region src/components/pagination.d.ts
+declare const paginationCss: (this: void, options?: ComponentOptions) => string;
+//#endregion
+//#region src/components/truncate.d.ts
+declare const truncateCss: (this: void, options?: ComponentOptions) => string;
+//#endregion
+//#region src/components/toggle-details.d.ts
+declare const toggleDetailsCss: (this: void, options?: ComponentOptions) => string;
+//#endregion
+//#region src/components/file-drop.d.ts
+declare const fileDropCss: (this: void, options?: ComponentOptions) => string;
+//#endregion
+//#region src/components/side-nav-bar.d.ts
+declare const sideNavBarCss: (this: void, options?: ComponentOptions) => string;
+//#endregion
+//#region src/components/tree-browser.d.ts
+declare const treeBrowserCss: (this: void, options?: ComponentOptions) => string;
+//#endregion
+//#region src/components/calendar.d.ts
+declare const calendarCss: (this: void, options?: ComponentOptions) => string;
+//#endregion
+//#region src/components/popover.d.ts
+declare const popoverCss: (this: void, options?: ComponentOptions) => string;
+//#endregion
+//#region src/components/tray.d.ts
+declare const trayCss: (this: void, options?: ComponentOptions) => string;
+//#endregion
+//#region src/components/tooltip.d.ts
+declare const tooltipCss: (this: void, options?: ComponentOptions) => string;
+//#endregion
+//#region src/components/range-input.d.ts
+declare const rangeInputCss: (this: void, options?: ComponentOptions) => string;
+//#endregion
+//#region src/components/heading.d.ts
+declare const headingCss: (this: void, options?: ComponentOptions) => string;
+//#endregion
+//#region src/components/text.d.ts
+declare const textCss: (this: void, options?: ComponentOptions) => string;
+//#endregion
+//#region src/components/close-button.d.ts
+declare const closeButtonCss: (this: void, options?: ComponentOptions) => string;
+//#endregion
+//#region src/components/text-input.d.ts
+declare const textInputCss: (this: void, options?: ComponentOptions) => string;
+//#endregion
+//#region src/components/text-area.d.ts
+declare const textAreaCss: (this: void, options?: ComponentOptions) => string;
+//#endregion
+//#region src/components/simple-select.d.ts
+declare const simpleSelectCss: (this: void, options?: ComponentOptions) => string;
+//#endregion
+//#region src/components/input-group.d.ts
+declare const inputGroupCss: (this: void, options?: ComponentOptions) => string;
+//#endregion
+//#region src/components/number-input.d.ts
+declare const numberInputCss: (this: void, options?: ComponentOptions) => string;
+//#endregion
+//#region src/components/in-place-edit.d.ts
+declare const inPlaceEditCss: (this: void, options?: ComponentOptions) => string;
+//#endregion
+//#region src/components/form-field-messages.d.ts
+declare const formFieldMessagesCss: (this: void, options?: ComponentOptions) => string;
+//#endregion
+//#region src/components/form-field.d.ts
+declare const formFieldCss: (this: void, options?: ComponentOptions) => string;
+//#endregion
+//#region src/components/form-field-group.d.ts
+declare const formFieldGroupCss: (this: void, options?: ComponentOptions) => string;
+//#endregion
+//#region src/components/radio-input-group.d.ts
+declare const radioInputGroupCss: (this: void, options?: ComponentOptions) => string;
+//#endregion
+//#region src/components/select.d.ts
+/**
+ * The **experimental** customizable-select enhancement for `.<prefix>-simple-select`. Everything is
+ * gated behind `@supports (appearance: base-select)` (the CSS Customizable Select model — Chrome 135+,
+ * NOT yet Baseline), so it's pure progressive enhancement: browsers without support keep the plain
+ * `simpleSelectCss` control; supporting browsers get a styled `::picker(select)` panel and styled
+ * `option`s (hover/selected) from the `--instui-component-options-item-*` tokens. Shipped as its own
+ * opt-in `select.css` (like `fonts.css`) rather than folded into `components.css`, precisely because the
+ * feature is experimental — you opt in deliberately.
+ *
+ * @param options - {@link ComponentOptions}.
+ * @returns The CSS string.
+ *
+ * @example
+ * ```ts
+ * import { selectCss } from "@pantoken/components";
+ *
+ * // Load AFTER components.css; enhances the same <select class="instui-simple-select"> element.
+ * const css = selectCss();
+ * ```
+ *
+ * @demo self:simple-select
+ */
+declare function selectCss(options?: ComponentOptions): string;
+//#endregion
+//#region src/utilities/view.d.ts
+declare const viewCss: (this: void, options?: ComponentOptions) => string;
+//#endregion
+//#region src/utilities/spacing.d.ts
+declare const spacingUtilitiesCss: (this: void, options?: ComponentOptions) => string;
+//#endregion
+//#region src/utilities/layout.d.ts
+declare const layoutUtilitiesCss: (this: void, options?: ComponentOptions) => string;
+//#endregion
+//#region src/utilities/responsive.d.ts
+declare const responsiveUtilitiesCss: (this: void, options?: ComponentOptions) => string;
+//#endregion
+//#region src/utilities/icon.d.ts
+declare const iconCss: (this: void, options?: ComponentOptions) => string;
+//#endregion
+//#region src/utilities/mask.d.ts
+declare const maskCss: (this: void, options?: ComponentOptions) => string;
+//#endregion
+//#region src/utilities/screen-reader-content.d.ts
+declare const screenReaderContentCss: (this: void, options?: ComponentOptions) => string;
+//#endregion
+//#region src/utilities/icon-glyphs.d.ts
+/** Options for {@link iconGlyphsCss}. */
+interface IconGlyphsOptions extends ComponentOptions {
+  /**
+   * Also emit the deprecated InstUI-prop glyph aliases (`-render-icon-<name>`, `-render-custom-icon-<name>`)
+   * as functional aliases of `-icon-<name>`. Off by default — turning it on roughly doubles the sheet, so
+   * enable it only when you need markup written against the old `renderIcon`/`renderCustomIcon` prop names
+   * to keep rendering. The shipped `icons.css` is built with this on.
+   */
+  deprecatedAliases?: boolean;
+}
+/**
+ * Build the icon-glyph stylesheet: one `.<prefix>-icon-<name>` class per icon that points
+ * `--pantoken-glyph` at the matching `--instui-icon-<name>` token. Kept out of the component bundle
+ * (it's large); ships as its own `icons.css`. Pass the icon names (e.g. from `@pantoken/icons`).
+ *
+ * @param names - Icon names without the `--instui-icon-` prefix (e.g. `["megaphone", "check"]`).
+ * @param options - {@link IconGlyphsOptions} (adds `deprecatedAliases` to {@link ComponentOptions}).
+ * @returns The CSS string.
+ *
+ * @example
+ * ```ts
+ * import { iconGlyphsCss } from "@pantoken/components";
+ * import { icons } from "@pantoken/icons";
+ *
+ * const css = iconGlyphsCss(icons.map((i) => i.name)); // .-icon-megaphone { --pantoken-glyph: … }
+ * ```
+ *
+ * This is the glyph-token half of the icon system (the `.-icon-<name>` modifiers, shipped as
+ * `icons.css`); the `icon` utility is the painter half (the shared `::before`). They share the `icon`
+ * demo.
+ */
+declare function iconGlyphsCss(names: readonly string[], options?: IconGlyphsOptions): string;
+//#endregion
+//#region src/index.d.ts
+/**
+ * Build the opt-in base/reset stylesheet: global document defaults from the tokens (box-sizing, body
+ * reset, page surface, base text colour/font, `color-scheme`, base link), followed by the focus ring
+ * (a document-level default that targets bare focusables). Load it once, ahead of the component and
+ * prose sheets, when pantoken owns the page.
+ *
+ * @returns The CSS string.
+ */
+declare function baseCss(): string;
+/**
+ * Build the aggregated component stylesheet: the `--instui-elevation-*` scale (so shadows are intrinsic)
+ * followed by every component's rules in the `COMPONENTS` concat order. The size-alias and
+ * deprecated-alias twins are appended PER COMPONENT (within its own chunk) so each alias documents on
+ * its own page — the deprecated aliases are discovered from each record's `@deprecated {@link -x}`
+ * metadata (see `withAliases`), not a central hand-kept list.
+ *
+ * @param options - {@link ComponentOptions}.
+ * @returns The CSS string.
+ */
+declare function componentsCss(options?: ComponentOptions): string;
+//#endregion
+export { type ComponentOptions, DEFAULT_PREFIX, ELEVATION_NAMES, FOCUSABLE_SELECTOR, type IconGlyphsOptions, type ProseOptions, alertCss, avatarCss, badgeCss, baseCss, billboardCss, breadcrumbCss, buttonCss, bylineCss, calendarCss, checkboxCss, closeButtonCss, componentsCss, contextViewCss, elevationCss, elevationDeclarations, fileDropCss, focusOutlineCss, focusOutlineDeclarations, focusOutlineRules, formFieldCss, formFieldGroupCss, formFieldMessagesCss, headingCss, iconCss, iconGlyphsCss, imgCss, inPlaceEditCss, inputGroupCss, layoutUtilitiesCss, linkCss, listCss, maskCss, menuCss, metricCss, modalCss, numberInputCss, paginationCss, pillCss, popoverCss, progressCircleCss, progressCss, proseCss, radioCss, radioInputGroupCss, rangeInputCss, ratingCss, responsiveUtilitiesCss, screenReaderContentCss, selectCss, sideNavBarCss, simpleSelectCss, spacingUtilitiesCss, spinnerCss, tableCss, tabsCss, tagCss, textAreaCss, textCss, textInputCss, toggleDetailsCss, toggleGroupCss, tooltipCss, trayCss, treeBrowserCss, truncateCss, viewCss };