@kosdev-code/base-ui-components 2.0.0 → 2.0.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kosdev-code/base-ui-components",
-  "version": "2.0.0",
+  "version": "2.0.1",
   "main": "./index.cjs",
   "module": "./index.js",
   "types": "./index.d.ts",
@@ -35,7 +35,7 @@
   },
   "kos": {
     "build": {
-      "gitHash": "c09dd2be8a2d174b34f2c36653eb31c517fc18b5"
+      "gitHash": "ca09b5f1aeb43f3bbc8cfc0e9553e6a5d856718c"
     }
   }
 }

package/styles/tokens/common/local-token-helpers.d.ts

@@ -0,0 +1,166 @@
+/**
+ * Utilities for creating local component tokens in consuming applications.
+ *
+ * These helpers allow applications to extend the design token system with their own
+ * component tokens while maintaining consistency with the base library's patterns.
+ *
+ * @example
+ * ```typescript
+ * // my-app/src/styles/tokens/local-components/custom-card.ts
+ * import { getSemanticToken as st } from '@kosdev-code/base-ui-components/styles';
+ *
+ * export const CUSTOM_CARD_TOKENS = {
+ *   'custom-card': {
+ *     padding: st('spacing-16'),
+ *     'background-color': st('color-white'),
+ *     'border-color': st('color-grey20'),
+ *   },
+ * } as const;
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // my-app/src/styles/tokens/index.ts
+ * import { createLocalTokenSystem } from '@kosdev-code/base-ui-components/styles';
+ * import { CUSTOM_CARD_TOKENS } from './local-components/custom-card';
+ *
+ * const LOCAL_TOKENS = {
+ *   ...CUSTOM_CARD_TOKENS,
+ * } as const;
+ *
+ * export const {
+ *   getLocalComponentTokenHelpers,
+ *   localComponentTokenCss,
+ * } = createLocalTokenSystem(LOCAL_TOKENS);
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // my-app/src/components/custom-card/custom-card.tsx
+ * import { getLocalComponentTokenHelpers } from '../../styles/tokens';
+ *
+ * const [ct] = getLocalComponentTokenHelpers(['custom-card']);
+ *
+ * const StyledCard = styled.div`
+ *   padding: ${ct('padding')};
+ *   background-color: ${ct('background-color')};
+ * `;
+ * ```
+ */
+/**
+ * Type utility to extract token string keys from a token definition object.
+ */
+export type ExtractLocalTokenString<T> = T extends Record<string, infer U> ? U extends string ? U : never : never;
+/**
+ * Transforms a token object into CSS custom property declarations.
+ *
+ * @param tokens - Object mapping namespaces to token definitions
+ * @param prefix - CSS custom property prefix (default: 'studio-c')
+ * @returns Array of CSS custom property declarations
+ *
+ * @internal
+ */
+export declare const transformLocalTokenObject: (tokens: Record<string, Record<string, string>>, prefix?: string) => string[];
+/**
+ * Creates a complete local token system with typed helpers and CSS injection.
+ *
+ * This function generates the same API as the base library's component token system,
+ * allowing consuming applications to create their own component tokens that integrate
+ * seamlessly with the base design tokens.
+ *
+ * @param tokens - Local component token definitions
+ * @param options - Configuration options
+ * @param options.prefix - CSS custom property prefix (default: 'studio-c')
+ * @param options.cssRootSelector - CSS selector for token injection (default: ':root')
+ *
+ * @returns Object containing token helpers and CSS injection
+ *
+ * @example
+ * ```typescript
+ * const LOCAL_TOKENS = {
+ *   'custom-card': {
+ *     padding: 'var(--studio-s-spacing-16)',
+ *     bg: 'var(--studio-s-color-white)',
+ *   },
+ *   'custom-panel': {
+ *     width: '300px',
+ *     bg: 'var(--studio-s-color-grey10)',
+ *   },
+ * } as const;
+ *
+ * const {
+ *   getLocalComponentTokenHelpers,
+ *   localComponentTokenCss,
+ * } = createLocalTokenSystem(LOCAL_TOKENS);
+ *
+ * // Use in application root
+ * <Global styles={[
+ *   globalStudioTokenCss,
+ *   semanticStudioTokenCss,
+ *   componentStudioTokenCss,
+ *   localComponentTokenCss,  // ← Your local tokens
+ * ]} />
+ *
+ * // Use in components
+ * const [ct] = getLocalComponentTokenHelpers(['custom-card']);
+ * const StyledCard = styled.div`
+ *   padding: ${ct('padding')};
+ * `;
+ * ```
+ */
+export declare const createLocalTokenSystem: <T extends Record<string, Record<string, string>>>(tokens: T, options?: {
+    prefix?: string;
+    cssRootSelector?: string;
+}) => {
+    getLocalComponentTokenHelpers: <N extends readonly (keyof T)[]>(namespaces: [...N]) => { [Key in keyof N]: (key: ExtractLocalTokenString<T[N[Key]]>, asKey?: boolean) => string; };
+    localComponentTokenCss: import('@emotion/react').SerializedStyles;
+};
+/**
+ * Creates a typed token getter function for a single component namespace.
+ *
+ * Useful for quick components or when you don't need the full token system setup.
+ *
+ * @param namespace - Component namespace
+ * @param prefix - CSS custom property prefix (default: 'studio-c')
+ * @returns Typed token getter function
+ *
+ * @example
+ * ```typescript
+ * // Quick helper for a single component
+ * const ct = createLocalComponentHelper<'padding' | 'bg' | 'color'>('quick-widget');
+ *
+ * const StyledWidget = styled.div`
+ *   padding: ${ct('padding')};
+ *   background: ${ct('bg')};
+ *   color: ${ct('color')};
+ * `;
+ * ```
+ */
+export declare const createLocalComponentHelper: <TKeys extends string>(namespace: string, prefix?: string) => (key: TKeys, asKey?: boolean) => string;
+/**
+ * Creates CSS for injecting local component tokens inline or in specific scopes.
+ *
+ * Use this when you want to define tokens programmatically or scope them
+ * to specific parts of your application.
+ *
+ * @param tokens - Token definitions
+ * @param options - Configuration options
+ * @returns Emotion CSS object
+ *
+ * @example
+ * ```typescript
+ * // Scoped tokens for a specific section
+ * const ThemedSection = styled.div`
+ *   ${createLocalComponentTokenCss({
+ *     'custom-card': {
+ *       'background-color': 'var(--studio-s-color-grey10)',
+ *       'border-color': 'var(--studio-s-color-grey30)',
+ *     },
+ *   })}
+ * `;
+ * ```
+ */
+export declare const createLocalComponentTokenCss: (tokens: Record<string, Record<string, string>>, options?: {
+    prefix?: string;
+}) => import('@emotion/react').SerializedStyles;
+//# sourceMappingURL=local-token-helpers.d.ts.map

package/styles/tokens/common/local-token-helpers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"local-token-helpers.d.ts","sourceRoot":"","sources":["../../../../../../../packages/libraries/base-ui-components/src/styles/tokens/common/local-token-helpers.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgDG;AAKH;;GAEG;AACH,MAAM,MAAM,uBAAuB,CAAC,CAAC,IAAI,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,GACtE,CAAC,SAAS,MAAM,GACd,CAAC,GACD,KAAK,GACP,KAAK,CAAC;AAEV;;;;;;;;GAQG;AACH,eAAO,MAAM,yBAAyB,WAC5B,OAAO,MAAM,EAAE,OAAO,MAAM,EAAE,MAAM,CAAC,CAAC,sBAE7C,MAAM,EAKN,CAAC;AAEJ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8CG;AACH,eAAO,MAAM,sBAAsB,6DAGzB,CAAC,YACA;IACP,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B;gFA6Ba,CAAC,GAAG,CAAC,CAAC,2EAIR,OAAO,KACZ,MAAM;;CAoCd,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,eAAO,MAAM,0BAA0B,oCACH,MAAM,4BAClC,KAAK,UAAU,OAAO,WAC2B,CAAC;AAE1D;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,eAAO,MAAM,4BAA4B,WAC/B,OAAO,MAAM,EAAE,OAAO,MAAM,EAAE,MAAM,CAAC,CAAC,YACrC;IACP,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB,8CAOF,CAAC"}

package/styles/tokens/index.d.ts

@@ -3,6 +3,8 @@ import { ExtractTokenString } from './common/types';
 import { getGlobalToken, getSemanticToken } from './common/token-getters';
 
 export { getGlobalToken, getSemanticToken };
+export { createLocalTokenSystem, createLocalComponentHelper, createLocalComponentTokenCss, transformLocalTokenObject, } from './common/local-token-helpers';
+export type { ExtractLocalTokenString } from './common/local-token-helpers';
 export { TagColor };
 export declare const getComponentTokenHelpers: <T extends readonly ("link" | "multi-select" | "shell-icon-button" | "file-picker" | "resizable-panels" | "table" | "artifact-store-settings" | "branded-header" | "ingredient-card" | "error-list-item" | "named-list-item" | "shell-menu" | "select-view-list" | "badge" | "radio-button" | "combobox" | "version-list-container" | "version-list-header" | "toggle-container" | "toggle-track" | "toggle-thumb" | "textarea" | "tag" | "tab" | "text" | "label" | "label-with-action" | "label-with-content-link" | "button" | "select" | "option" | "segmented" | "named-section" | "named-section-header" | "modal" | "input" | "image-config-page-header" | "icon" | "icon-button" | "horizontal-rule" | "form" | "drawer" | "collapsible-list-container" | "collapsible-list-header-container" | "collapsible-list-toggled-container" | "collapsible-artifact" | "collapsible-artifact-version" | "checkbox" | "artifact-drawer" | "app-shell" | "actionable-blurb")[]>(namespaces: [...T]) => { [Key in keyof T]: (key: ExtractTokenString<{
     readonly "multi-select": {

package/styles/tokens/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../../packages/libraries/base-ui-components/src/styles/tokens/index.tsx"],"names":[],"mappings":"AACA,OAAO,EACL,cAAc,EACd,gBAAgB,EAEjB,MAAM,wBAAwB,CAAC;AAChC,OAAO,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAC;AACpD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AACnD,OAAO,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAItD,OAAO,EAAE,cAAc,EAAE,gBAAgB,EAAE,CAAC;AAE5C,OAAO,EAAE,QAAQ,EAAE,CAAC;AACpB,eAAO,MAAM,wBAAwB,67BAGvB,CAAC,GAAG,CAAC,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;oBAIR,OAAO,KACZ,MAAM,GAMV,CAAC;AAeJ,eAAO,MAAM,sBAAsB,2CAIlC,CAAC;AAEF,eAAO,MAAM,oBAAoB,2CAQhC,CAAC;AAEF,eAAO,MAAM,uBAAuB,2CAMnC,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../../packages/libraries/base-ui-components/src/styles/tokens/index.tsx"],"names":[],"mappings":"AACA,OAAO,EACL,cAAc,EACd,gBAAgB,EAEjB,MAAM,wBAAwB,CAAC;AAChC,OAAO,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAC;AACpD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AACnD,OAAO,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAItD,OAAO,EAAE,cAAc,EAAE,gBAAgB,EAAE,CAAC;AAG5C,OAAO,EACL,sBAAsB,EACtB,0BAA0B,EAC1B,4BAA4B,EAC5B,yBAAyB,GAC1B,MAAM,8BAA8B,CAAC;AACtC,YAAY,EAAE,uBAAuB,EAAE,MAAM,8BAA8B,CAAC;AAE5E,OAAO,EAAE,QAAQ,EAAE,CAAC;AACpB,eAAO,MAAM,wBAAwB,67BAGvB,CAAC,GAAG,CAAC,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;oBAIR,OAAO,KACZ,MAAM,GAMV,CAAC;AAeJ,eAAO,MAAM,sBAAsB,2CAIlC,CAAC;AAEF,eAAO,MAAM,oBAAoB,2CAQhC,CAAC;AAEF,eAAO,MAAM,uBAAuB,2CAMnC,CAAC"}