@pharos-ds/core 0.1.9

package/dist/i18n/types.d.ts

@@ -0,0 +1,47 @@
+/**
+ * @file types.ts
+ * @input None
+ * @output Shared types for the i18n subpackage
+ * @position Type-only module; used across client + server t() implementations
+ *
+ * SYNC: When modified, update these files to stay in sync:
+ * - /packages/core/src/i18n/InternationalizationContext.ts
+ * - /packages/core/src/i18n/InternationalizationProvider.tsx
+ * - /packages/core/src/i18n/serverStore.ts
+ * - /packages/core/src/i18n/resolve.ts
+ */
+/**
+ * A BCP 47 language tag. Examples: `'en'`, `'pt'`, `'pt-BR'`, `'zh-Hans'`.
+ *
+ * Regional tags are meaningful — `pt-BR` and `pt` are different catalogs.
+ * When resolving a message, the runtime walks the tag from most-specific
+ * to least-specific and falls back to `en` if nothing matches
+ * (see `resolveLocaleChain` in `resolve.ts`).
+ */
+export type Locale = string;
+/**
+ * A single entry in a translation catalog. The `defaultMessage` is an ICU
+ * MessageFormat string; `description` is optional context for translators
+ * (surfaced by Crowdin's `react_intl` file type parser).
+ */
+export interface MessageEntry {
+    defaultMessage: string;
+    description?: string;
+}
+/**
+ * A translation catalog — a map of stable message keys to entries.
+ * Pharos's own keys are namespaced under `@pharos.<component>.<name>`.
+ */
+export type Catalog = Record<string, MessageEntry>;
+/**
+ * A map of BCP 47 tags to catalogs. Passed as `messages` on
+ * `<InternationalizationProvider>`.
+ */
+export type MessagesByLocale = Record<Locale, Catalog>;
+/**
+ * Sparse per-locale overrides applied on top of the shipped defaults.
+ * Only the keys the consumer cares to override need to be listed.
+ * Overrides are locale-keyed so a runtime locale swap picks up the right ones.
+ */
+export type Overrides = Partial<Record<Locale, Record<string, string>>>;
+//# sourceMappingURL=types.d.ts.map

package/dist/i18n/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/i18n/types.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;GAWG;AAEH;;;;;;;GAOG;AACH,MAAM,MAAM,MAAM,GAAG,MAAM,CAAC;AAE5B;;;;GAIG;AACH,MAAM,WAAW,YAAY;IAC3B,cAAc,EAAE,MAAM,CAAC;IACvB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED;;;GAGG;AACH,MAAM,MAAM,OAAO,GAAG,MAAM,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC;AAEnD;;;GAGG;AACH,MAAM,MAAM,gBAAgB,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAEvD;;;;GAIG;AACH,MAAM,MAAM,SAAS,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC"}

package/dist/i18n/types.js

@@ -0,0 +1 @@
+export {};

package/dist/i18n/useDirection.d.ts

@@ -0,0 +1,2 @@
+export declare function useDirection(): 'ltr' | 'rtl';
+//# sourceMappingURL=useDirection.d.ts.map

package/dist/i18n/useDirection.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useDirection.d.ts","sourceRoot":"","sources":["../../src/i18n/useDirection.ts"],"names":[],"mappings":"AAyBA,wBAAgB,YAAY,IAAI,KAAK,GAAG,KAAK,CAG5C"}

package/dist/i18n/useDirection.js

@@ -0,0 +1,27 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file useDirection.ts
+ * @input InternationalizationContext (via use())
+ * @output 'ltr' | 'rtl'
+ * @position Client hook for reading the ambient text direction. Returns 'ltr'
+ *   when called outside a provider (matches the silent-en-fallback pattern of
+ *   useTranslator).
+ *
+ * Use this in components that need to swap directional icons, mirror
+ * behavioral logic (slider math, keyboard nav), or apply direction-specific
+ * styling that CSS logical properties can't express.
+ *
+ * SYNC: When modified, update these files to stay in sync:
+ * - /packages/core/src/i18n/InternationalizationContext.ts
+ * - /packages/core/src/i18n/getLocaleDirection.ts (server-safe counterpart)
+ * - /packages/core/src/i18n/index.ts
+ */
+import { use } from 'react';
+import { InternationalizationContext } from "./InternationalizationContext.js";
+export function useDirection() {
+  const ctx = use(InternationalizationContext);
+  return ctx.direction;
+}

package/dist/i18n/useTranslator.d.ts

@@ -0,0 +1,15 @@
+export type TranslatorFn = (key: string, values?: Record<string, unknown>) => string;
+/**
+ * Returns a translator function bound to the current provider's locale.
+ * Safe to call from event handlers and effects.
+ *
+ * @example
+ * ```
+ * function MyComponent() {
+ *   const translate = useTranslator();
+ *   const onClick = () => announce(translate('@pharos.pagination.pageAnnounce', {current: 1}));
+ * }
+ * ```
+ */
+export declare function useTranslator(): TranslatorFn;
+//# sourceMappingURL=useTranslator.d.ts.map

package/dist/i18n/useTranslator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useTranslator.d.ts","sourceRoot":"","sources":["../../src/i18n/useTranslator.ts"],"names":[],"mappings":"AAyBA,MAAM,MAAM,YAAY,GAAG,CACzB,GAAG,EAAE,MAAM,EACX,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAC7B,MAAM,CAAC;AAEZ;;;;;;;;;;;GAWG;AACH,wBAAgB,aAAa,IAAI,YAAY,CAO5C"}

package/dist/i18n/useTranslator.js

@@ -0,0 +1,39 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file useTranslator.ts
+ * @input InternationalizationContext (via use())
+ * @output Exports useTranslator hook returning a stable translator function
+ * @position Client-side hook for translating outside of render (event handlers,
+ *   effects, non-component code) while still resolving against the current
+ *   provider's locale.
+ *
+ * Prefer `t()` for translations at the callsite during render. When you need
+ * to translate inside an event handler or effect, capture a translator during
+ * render via useTranslator() and call it later.
+ *
+ * SYNC: When modified, update these files to stay in sync:
+ * - /packages/core/src/i18n/index.ts
+ * - /packages/core/src/i18n/t.client.ts
+ */
+import { use, useCallback } from 'react';
+import { InternationalizationContext } from "./InternationalizationContext.js";
+import { resolve } from "./resolve.js";
+/**
+ * Returns a translator function bound to the current provider's locale.
+ * Safe to call from event handlers and effects.
+ *
+ * @example
+ * ```
+ * function MyComponent() {
+ *   const translate = useTranslator();
+ *   const onClick = () => announce(translate('@pharos.pagination.pageAnnounce', {current: 1}));
+ * }
+ * ```
+ */
+export function useTranslator() {
+  const ctx = use(InternationalizationContext);
+  return useCallback((key, values) => resolve(key, values, ctx.locale, ctx.messages, ctx.overrides), [ctx.locale, ctx.messages, ctx.overrides]);
+}

package/dist/index.d.ts

@@ -0,0 +1,113 @@
+/**
+ * @file index.ts
+ * @input Imports from component directories (Button/, Card/, Layout/, Layer/, Toast/)
+ * @output Exports all public components, hooks, and types for @pharos-ds/core
+ * @position Package entry point; consumed by external applications
+ *
+ * SYNC: When modified, update this header and /packages/core/src/README.md
+ */
+export type { BaseProps } from './BaseProps';
+export * from './AppShell';
+export * from './AspectRatio';
+export * from './Avatar';
+export * from './AvatarGroup';
+export * from './Badge';
+export * from './Banner';
+export * from './Blockquote';
+export * from './Breadcrumbs';
+export * from './Button';
+export * from './ButtonGroup';
+export * from './IconButton';
+export * from './Card';
+export * from './ClickableCard';
+export * from './Carousel';
+export * from './Calendar';
+export * from './Center';
+export * from './CodeBlock';
+export * from './CommandPalette';
+export * from './Chat';
+export * from './Markdown';
+export * from './Citation';
+export * from './CheckboxInput';
+export * from './CheckboxList';
+export * from './Collapsible';
+export * from './RadioList';
+export * from './Resizable';
+export * from './Divider';
+export * from './VisuallyHidden';
+export * from './EmptyState';
+export * from './Lightbox';
+export * from './Link';
+export * from './List';
+export * from './MetadataList';
+export * from './NavIcon';
+export * from './NavMenu';
+export * from './Slider';
+export * from './Stack';
+export * from './Switch';
+export * from './DateInput';
+export * from './DateTimeInput';
+export * from './DateRangeInput';
+export * from './Field';
+export * from './FileInput';
+export * from './FormLayout';
+export * from './Grid';
+export * from './Section';
+export * from './SegmentedControl';
+export * from './SelectableCard';
+export * from './Selector';
+export * from './MultiSelector';
+export * from './Icon';
+export * from './InputGroup';
+export * from './Item';
+export * from './Text';
+export * from './TextInput';
+export * from './TabList';
+export * from './TextArea';
+export * from './TimeInput';
+export * from './NumberInput';
+export * from './Table';
+export * from './ToggleButton';
+export * from './Token';
+export * from './Typeahead';
+export * from './Tokenizer';
+export * from './Thumbnail';
+export * from './PowerSearch';
+export * from './TreeList';
+export * from './Kbd';
+export * from './AlertDialog';
+export * from './Dialog';
+export * from './ContextMenu';
+export * from './DropdownMenu';
+export * from './MoreMenu';
+export * from './InteractiveRoleContext';
+export * from './SizeContext';
+export * from './Toolbar';
+export * from './TopNav';
+export * from './SideNav';
+export * from './MobileNav';
+export * from './Pagination';
+export * from './ProgressBar';
+export * from './Layout';
+export { useLayer } from './Layer';
+export type { LayerAlignment, LayerPlacement, ContextRenderProps, FixedRenderProps, ContextLayerOptions, FixedLayerOptions, ContextLayerReturn, FixedLayerReturn, } from './Layer';
+export { LayerProvider } from './Layer';
+export type { LayerProviderProps, LayerToastConfig } from './Layer';
+export { Toast, useToast } from './Toast';
+export type { ToastProps, ToastType, ToastPosition, ToastCollisionBehavior, ToastDismissReason, ToastOptions, ToastDismissFn, ShowToastFn, } from './Toast';
+export * from './Popover';
+export * from './HoverCard';
+export * from './Tooltip';
+export * from './Skeleton';
+export * from './StatusDot';
+export * from './Spinner';
+export * from './Timestamp';
+export * from './Overlay';
+export * from './Outline';
+export * from './OverflowList';
+export * from './hooks';
+export * from './utils';
+export * from './theme';
+export * from './i18n';
+export type { ComponentDoc, SingleComponentDoc, MultiComponentDoc, PropDoc, ComponentEntry, ThemingTarget, ComponentVar, DerivedVar, TranslationDoc, GroupDoc, ReferenceDoc, ReferenceSection, ContentBlock, TokenPreviewType, } from './docs-types';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/index.js

@@ -0,0 +1,150 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file index.ts
+ * @input Imports from component directories (Button/, Card/, Layout/, Layer/, Toast/)
+ * @output Exports all public components, hooks, and types for @pharos-ds/core
+ * @position Package entry point; consumed by external applications
+ *
+ * SYNC: When modified, update this header and /packages/core/src/README.md
+ */
+
+// Base types
+// Components
+export * from "./AppShell/index.js";
+export * from "./AspectRatio/index.js";
+export * from "./Avatar/index.js";
+export * from "./AvatarGroup/index.js";
+export * from "./Badge/index.js";
+export * from "./Banner/index.js";
+export * from "./Blockquote/index.js";
+export * from "./Breadcrumbs/index.js";
+export * from "./Button/index.js";
+export * from "./ButtonGroup/index.js";
+export * from "./IconButton/index.js";
+export * from "./Card/index.js";
+export * from "./ClickableCard/index.js";
+export * from "./Carousel/index.js";
+export * from "./Calendar/index.js";
+export * from "./Center/index.js";
+export * from "./CodeBlock/index.js";
+export * from "./CommandPalette/index.js";
+export * from "./Chat/index.js";
+export * from "./Markdown/index.js";
+export * from "./Citation/index.js";
+export * from "./CheckboxInput/index.js";
+export * from "./CheckboxList/index.js";
+export * from "./Collapsible/index.js";
+export * from "./RadioList/index.js";
+export * from "./Resizable/index.js";
+export * from "./Divider/index.js";
+export * from "./VisuallyHidden/index.js";
+export * from "./EmptyState/index.js";
+export * from "./Lightbox/index.js";
+export * from "./Link/index.js";
+export * from "./List/index.js";
+export * from "./MetadataList/index.js";
+export * from "./NavIcon/index.js";
+// NavItem (navItemStyles) is internal — shared styles consumed by SideNav/TopNav/MobileNav
+export * from "./NavMenu/index.js";
+export * from "./Slider/index.js";
+export * from "./Stack/index.js";
+export * from "./Switch/index.js";
+export * from "./DateInput/index.js";
+export * from "./DateTimeInput/index.js";
+export * from "./DateRangeInput/index.js";
+export * from "./Field/index.js";
+export * from "./FileInput/index.js";
+export * from "./FormLayout/index.js";
+export * from "./Grid/index.js";
+export * from "./Section/index.js";
+export * from "./SegmentedControl/index.js";
+export * from "./SelectableCard/index.js";
+export * from "./Selector/index.js";
+export * from "./MultiSelector/index.js";
+export * from "./Icon/index.js";
+export * from "./InputGroup/index.js";
+export * from "./Item/index.js";
+export * from "./Text/index.js";
+export * from "./TextInput/index.js";
+export * from "./TabList/index.js";
+export * from "./TextArea/index.js";
+export * from "./TimeInput/index.js";
+export * from "./NumberInput/index.js";
+export * from "./Table/index.js";
+export * from "./ToggleButton/index.js";
+export * from "./Token/index.js";
+export * from "./Typeahead/index.js";
+export * from "./Tokenizer/index.js";
+export * from "./Thumbnail/index.js";
+export * from "./PowerSearch/index.js";
+export * from "./TreeList/index.js";
+
+// Keyboard shortcut display
+export * from "./Kbd/index.js";
+export * from "./AlertDialog/index.js";
+export * from "./Dialog/index.js";
+export * from "./ContextMenu/index.js";
+export * from "./DropdownMenu/index.js";
+export * from "./MoreMenu/index.js";
+export * from "./InteractiveRoleContext/index.js";
+export * from "./SizeContext/index.js";
+export * from "./Toolbar/index.js";
+export * from "./TopNav/index.js";
+export * from "./SideNav/index.js";
+export * from "./MobileNav/index.js";
+export * from "./Pagination/index.js";
+export * from "./ProgressBar/index.js";
+
+// Layout utilities and components (includes HStack, VStack)
+export * from "./Layout/index.js";
+
+// Layer utilities (useLayer hook and core types)
+export { useLayer } from "./Layer/index.js";
+// Layer provider
+export { LayerProvider } from "./Layer/index.js";
+// Toast
+export { Toast, useToast } from "./Toast/index.js";
+// Popover component and hook
+export * from "./Popover/index.js";
+
+// HoverCard component and hook
+export * from "./HoverCard/index.js";
+
+// Tooltip component and hook
+export * from "./Tooltip/index.js";
+
+// Skeleton loading placeholder
+export * from "./Skeleton/index.js";
+
+// Status dot indicator
+export * from "./StatusDot/index.js";
+
+// Spinner loading indicator
+export * from "./Spinner/index.js";
+
+// Timestamp display
+export * from "./Timestamp/index.js";
+
+// Overlay
+export * from "./Overlay/index.js";
+export * from "./Outline/index.js";
+
+// Overflow list
+export * from "./OverflowList/index.js";
+
+// Hooks
+export * from "./hooks/index.js";
+
+// Utilities
+export * from "./utils/index.js";
+
+// Theme
+export * from "./theme/index.js";
+
+// Internationalization
+export * from "./i18n/index.js";
+
+// Doc types — for external library authors writing .doc.mjs files

package/dist/naming.d.ts

@@ -0,0 +1,69 @@
+/**
+ * @file naming.ts
+ * @input None (pure constants/helpers)
+ * @output Centralized namespace-prefix constants and helpers for all
+ *   externally-observable name surfaces: CSS classes, data attributes,
+ *   CSS custom properties, and CSS layer names.
+ * @position Single source of truth consumed by the runtime (components,
+ *   theme generation) AND by build/CLI tooling (build-theme.mjs, discovery)
+ *   via the `@pharos-ds/core/naming` subpath export.
+ *
+ * ## Why this module exists
+ *
+ * The namespace prefix `pharos` is part of several externally-observable
+ * contracts (`.pharos-button` classes, `data-pharos-theme` attributes,
+ * `--pharos-card-padding` custom properties). Historically each of these was
+ * hardcoded independently across the runtime, the theme build pipeline, and
+ * discovery tooling, kept in sync only by `<!-- SYNC: ... -->` comments.
+ * Centralizing the prefix here means it lives in ONE place instead of
+ * hundreds of literals.
+ *
+ * ## Surfaces
+ *
+ * - CSS classes: `.pharos-button` via {@link classPrefix} / {@link stableClassName}.
+ * - data attributes: `data-pharos-*` via {@link dataAttrNamespace} / {@link dataAttr}.
+ * - CSS custom properties: `--pharos-*` via {@link cssVarNamespace} / {@link cssVar}.
+ * - CSS layers: `pharos-base` / `pharos-theme`.
+ *
+ * SYNC: packages/core/src/utils/themeProps.ts (consumes classPrefix)
+ * SYNC: packages/core/src/utils/parseStyleKey.ts
+ * SYNC: packages/cli/src/commands/build-theme.mjs (imports @pharos-ds/core/naming)
+ */
+/**
+ * The DOM/CSS namespace prefix for all externally-observable surfaces
+ * (classes, theme/media data attributes, CSS custom properties).
+ */
+export declare const NAMESPACE = "pharos";
+/**
+ * Class-name prefix for stable component classes, WITHOUT the trailing dash.
+ *
+ * Use {@link stableClassName} to build a full class token rather than
+ * concatenating this directly.
+ */
+export declare const classPrefix = "pharos";
+/**
+ * data-attribute namespace segment (the part between `data-` and the rest).
+ * e.g. `dataAttrNamespace` = 'pharos' -> `data-pharos-theme`.
+ */
+export declare const dataAttrNamespace = "pharos";
+/**
+ * CSS custom-property namespace segment.
+ * e.g. `--pharos-card-padding`.
+ */
+export declare const cssVarNamespace = "pharos";
+/**
+ * Build a stable component class token, e.g. `stableClassName('button')`
+ * -> `'pharos-button'`.
+ */
+export declare function stableClassName(component: string): string;
+/**
+ * Build a `data-*` attribute name in the current namespace, e.g.
+ * `dataAttr('theme')` -> `'data-pharos-theme'`.
+ */
+export declare function dataAttr(name: string): `data-${string}`;
+/**
+ * Build a CSS custom-property name in the current namespace, e.g.
+ * `cssVar('card-padding')` -> `'--pharos-card-padding'`.
+ */
+export declare function cssVar(name: string): string;
+//# sourceMappingURL=naming.d.ts.map

package/dist/naming.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"naming.d.ts","sourceRoot":"","sources":["../src/naming.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAEH;;;GAGG;AACH,eAAO,MAAM,SAAS,WAAW,CAAC;AAElC;;;;;GAKG;AACH,eAAO,MAAM,WAAW,WAAY,CAAC;AAErC;;;GAGG;AACH,eAAO,MAAM,iBAAiB,WAAY,CAAC;AAE3C;;;GAGG;AACH,eAAO,MAAM,eAAe,WAAY,CAAC;AAEzC;;;GAGG;AACH,wBAAgB,eAAe,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAEzD;AAED;;;GAGG;AACH,wBAAgB,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,QAAQ,MAAM,EAAE,CAEvD;AAED;;;GAGG;AACH,wBAAgB,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAE3C"}

package/dist/naming.js

@@ -0,0 +1,83 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file naming.ts
+ * @input None (pure constants/helpers)
+ * @output Centralized namespace-prefix constants and helpers for all
+ *   externally-observable name surfaces: CSS classes, data attributes,
+ *   CSS custom properties, and CSS layer names.
+ * @position Single source of truth consumed by the runtime (components,
+ *   theme generation) AND by build/CLI tooling (build-theme.mjs, discovery)
+ *   via the `@pharos-ds/core/naming` subpath export.
+ *
+ * ## Why this module exists
+ *
+ * The namespace prefix `pharos` is part of several externally-observable
+ * contracts (`.pharos-button` classes, `data-pharos-theme` attributes,
+ * `--pharos-card-padding` custom properties). Historically each of these was
+ * hardcoded independently across the runtime, the theme build pipeline, and
+ * discovery tooling, kept in sync only by `<!-- SYNC: ... -->` comments.
+ * Centralizing the prefix here means it lives in ONE place instead of
+ * hundreds of literals.
+ *
+ * ## Surfaces
+ *
+ * - CSS classes: `.pharos-button` via {@link classPrefix} / {@link stableClassName}.
+ * - data attributes: `data-pharos-*` via {@link dataAttrNamespace} / {@link dataAttr}.
+ * - CSS custom properties: `--pharos-*` via {@link cssVarNamespace} / {@link cssVar}.
+ * - CSS layers: `pharos-base` / `pharos-theme`.
+ *
+ * SYNC: packages/core/src/utils/themeProps.ts (consumes classPrefix)
+ * SYNC: packages/core/src/utils/parseStyleKey.ts
+ * SYNC: packages/cli/src/commands/build-theme.mjs (imports @pharos-ds/core/naming)
+ */
+
+/**
+ * The DOM/CSS namespace prefix for all externally-observable surfaces
+ * (classes, theme/media data attributes, CSS custom properties).
+ */
+export const NAMESPACE = 'pharos';
+
+/**
+ * Class-name prefix for stable component classes, WITHOUT the trailing dash.
+ *
+ * Use {@link stableClassName} to build a full class token rather than
+ * concatenating this directly.
+ */
+export const classPrefix = NAMESPACE;
+
+/**
+ * data-attribute namespace segment (the part between `data-` and the rest).
+ * e.g. `dataAttrNamespace` = 'pharos' -> `data-pharos-theme`.
+ */
+export const dataAttrNamespace = NAMESPACE;
+
+/**
+ * CSS custom-property namespace segment.
+ * e.g. `--pharos-card-padding`.
+ */
+export const cssVarNamespace = NAMESPACE;
+
+/**
+ * Build a stable component class token, e.g. `stableClassName('button')`
+ * -> `'pharos-button'`.
+ */
+export function stableClassName(component) {
+  return `${classPrefix}-${component}`;
+}
+
+/**
+ * Build a `data-*` attribute name in the current namespace, e.g.
+ * `dataAttr('theme')` -> `'data-pharos-theme'`.
+ */
+export function dataAttr(name) {
+  return `data-${dataAttrNamespace}-${name}`;
+}
+
+/**
+ * Build a CSS custom-property name in the current namespace, e.g.
+ * `cssVar('card-padding')` -> `'--pharos-card-padding'`.
+ */
+export function cssVar(name) {
+  return `--${cssVarNamespace}-${name}`;
+}