@ossy/types 0.2.1 → 0.3.1

package/README.md

@@ -1,18 +1,37 @@
 # @ossy/types
 
-Shared TypeScript types for all packages in the monorepo.
+Shared TypeScript types for the Ossy ecosystem. Defines interfaces for themes, SDK configuration, resources, workspaces, and more.
 
 ## Installation
 
-This package is part of the monorepo and can be used by other packages via:
+```bash
+npm install @ossy/types
+```
+
+## Usage
 
 ```typescript
-import { SomeType } from '@ossy/types';
+import type { Theme, Resource, SDKConfig, Workspace } from '@ossy/types'
 ```
 
-## Usage
+## Key types
+
+| Category | Types |
+|----------|-------|
+| **Theme & Design** | `Theme`, `SurfaceVariant`, `SpaceScale`, `MaxWidthScale`, `ColorPalette`, `SurfaceDefinitions`, `SurfacesMap` |
+| **SDK** | `SDKConfig`, `Action` |
+| **Resources** | `Resource`, `ResourceTemplate`, `Field`, `Workspace` |
+| **Jobs** | `Job` |
+
+## Documentation
 
-Add shared types to this package that need to be used across multiple packages in the monorepo.
+Full type documentation is available in Storybook. Run from the monorepo root:
+
+```bash
+npm start
+```
+
+Browse **Types** in the sidebar for generated interface tables.
 
 ## Development
 
@@ -21,3 +40,7 @@ Build the package:
 ```bash
 npm run build
 ```
+
+## License
+
+MIT

package/build/index.d.ts

@@ -1,13 +1,158 @@
 interface Field {
-    label: string;
+    label?: string;
     name: string;
     type: string;
-    description: string;
+    description?: string;
     placeholder?: string;
-    required: boolean;
+    required?: boolean;
     options?: string[];
 }
 
+/**
+ * CSS value - any valid CSS string (color, gradient, length, etc.)
+ */
+type CssValue = string;
+/**
+ * Recursive structure for CSS variable groups.
+ * Keys are CSS property names (kebab-case or camelCase).
+ * Values are either CSS strings or nested groups.
+ */
+type CssStyleGroup = {
+    [key: string]: CssValue | CssStyleGroup | undefined;
+};
+/**
+ * Surface variant - used for [data-surface="..."] blocks.
+ * Supports background, foreground, separator, backdropFilter, and state variants.
+ */
+interface SurfaceVariant extends CssStyleGroup {
+    background?: CssValue;
+    'background-hover'?: CssValue;
+    'background-active'?: CssValue;
+    foreground?: CssValue;
+    'foreground-hover'?: CssValue;
+    'foreground-active'?: CssValue;
+    separator?: CssValue;
+    backdropFilter?: CssValue;
+}
+/**
+ * Space scale - spacing tokens used throughout the design system.
+ */
+interface SpaceScale {
+    none?: CssValue;
+    xxs?: CssValue;
+    xs?: CssValue;
+    s?: CssValue;
+    m?: CssValue;
+    l?: CssValue;
+    xl?: CssValue;
+    xxl?: CssValue;
+    [key: string]: CssValue | undefined;
+}
+/**
+ * Max width scale - responsive container widths.
+ */
+interface MaxWidthScale {
+    xxs?: CssValue;
+    xs?: CssValue;
+    s?: CssValue;
+    m?: CssValue;
+    l?: CssValue;
+    xl?: CssValue;
+    xxl?: CssValue;
+    full?: CssValue;
+    [key: string]: CssValue | undefined;
+}
+/**
+ * Color palette - foreground, accent, and semantic colors.
+ * Cloud themes use either flat (Standard) or nested (CloudDark) structure.
+ */
+interface ColorPalette {
+    /** Flat structure (Standard, CloudLight) */
+    base?: CssValue;
+    primary?: CssValue;
+    secondary?: CssValue;
+    accent?: CssValue;
+    info?: CssValue;
+    danger?: CssValue;
+    'alt-primary'?: CssValue;
+    'alt-secondary'?: CssValue;
+    /** Nested structure (CloudDark) */
+    foreground?: {
+        primary?: CssValue;
+        secondary?: CssValue;
+    };
+    [key: string]: CssValue | {
+        primary?: CssValue;
+        secondary?: CssValue;
+    } | undefined;
+}
+/**
+ * Surface definitions - base surface colors and gradients.
+ */
+interface SurfaceDefinitions {
+    primary?: CssValue;
+    secondary?: CssValue;
+    base?: CssValue;
+    accent?: CssValue;
+    'radial-gradient'?: CssValue;
+    'linear-gradient'?: CssValue;
+    decorated?: CssValue;
+    [key: string]: CssValue | undefined;
+}
+/**
+ * Surfaces - named surface variants for components.
+ * Keys map to data-surface attribute values.
+ */
+interface SurfacesMap {
+    base?: SurfaceVariant;
+    primary?: SurfaceVariant;
+    secondary?: SurfaceVariant;
+    decorated?: SurfaceVariant;
+    'alt-primary'?: SurfaceVariant;
+    'alt-secondary'?: SurfaceVariant;
+    'radial-gradient'?: SurfaceVariant;
+    'linear-gradient'?: SurfaceVariant;
+    'alt-glass'?: SurfaceVariant;
+    info?: SurfaceVariant;
+    danger?: SurfaceVariant;
+    accent?: SurfaceVariant;
+    [key: string]: SurfaceVariant | undefined;
+}
+/**
+ * Theme - the complete design system theme structure.
+ * Based on cloud-light and cloud-dark (the canonical themes).
+ */
+interface Theme {
+    /** Spacing scale - maps to --space-* CSS variables */
+    space: SpaceScale;
+    /** Max width scale - maps to --max-width-* CSS variables */
+    'max-width': MaxWidthScale;
+    /** Color palette */
+    color?: ColorPalette;
+    /** Base surface definitions - maps to --surface-* */
+    surface: SurfaceDefinitions;
+    /** Surface variants - maps to [data-surface="key"] blocks */
+    surfaces: SurfacesMap;
+    /** Separator colors */
+    separator: CssStyleGroup;
+    /** Title/heading styles */
+    title: CssStyleGroup;
+    /** Body text styles */
+    text: CssStyleGroup;
+    /** Button variant styles */
+    button: CssStyleGroup;
+    /** Card variant styles */
+    card: CssStyleGroup;
+    /** Resume-specific styles */
+    resume?: CssStyleGroup;
+    /** Additional theme sections - allows extensibility */
+    [key: string]: SpaceScale | MaxWidthScale | CssStyleGroup | SurfacesMap | ColorPalette | SurfaceDefinitions | undefined;
+}
+/**
+ * Theme identifier - the canonical theme names.
+ */
+type ThemeId = 'cloud-light' | 'cloud-dark';
+
 interface Resource<T = any> {
     id: string;
     name: string;
@@ -23,8 +168,8 @@ interface Resource<T = any> {
 interface ResourceTemplate {
     id: string;
     name: string;
-    description: string;
-    icon: string;
+    description?: string;
+    icon?: string;
     fields: Field[];
 }
 
@@ -72,4 +217,4 @@ interface Job {
 }
 
 export { JobStatus, Jobs };
-export type { Action, Field, Job, JobStatusType, JobType, Resource, ResourceTemplate, SDKConfig, Workspace };
+export type { Action, ColorPalette, CssStyleGroup, CssValue, Field, Job, JobStatusType, JobType, MaxWidthScale, Resource, ResourceTemplate, SDKConfig, SpaceScale, SurfaceDefinitions, SurfaceVariant, SurfacesMap, Theme, ThemeId, Workspace };

package/build/types/docs/InterfaceTable.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Renders a TypeScript interface from ts2doc doc.json format as a table.
+ */
+export function InterfaceTable({ doc }: {
+    doc: any;
+}): React.JSX.Element | null;
+import React from 'react';

package/build/types/{Field.d.ts → src/Field.d.ts}

@@ -1,9 +1,9 @@
 export interface Field {
-    label: string;
+    label?: string;
     name: string;
     type: string;
-    description: string;
+    description?: string;
     placeholder?: string;
-    required: boolean;
+    required?: boolean;
     options?: string[];
 }

package/build/types/{ResourceTemplate.d.ts → src/ResourceTemplate.d.ts}

@@ -2,7 +2,7 @@ import { Field } from "./Field";
 export interface ResourceTemplate {
     id: string;
     name: string;
-    description: string;
-    icon: string;
+    description?: string;
+    icon?: string;
     fields: Field[];
 }

package/build/types/src/Theme.d.ts

@@ -0,0 +1,144 @@
+/**
+ * CSS value - any valid CSS string (color, gradient, length, etc.)
+ */
+export type CssValue = string;
+/**
+ * Recursive structure for CSS variable groups.
+ * Keys are CSS property names (kebab-case or camelCase).
+ * Values are either CSS strings or nested groups.
+ */
+export type CssStyleGroup = {
+    [key: string]: CssValue | CssStyleGroup | undefined;
+};
+/**
+ * Surface variant - used for [data-surface="..."] blocks.
+ * Supports background, foreground, separator, backdropFilter, and state variants.
+ */
+export interface SurfaceVariant extends CssStyleGroup {
+    background?: CssValue;
+    'background-hover'?: CssValue;
+    'background-active'?: CssValue;
+    foreground?: CssValue;
+    'foreground-hover'?: CssValue;
+    'foreground-active'?: CssValue;
+    separator?: CssValue;
+    backdropFilter?: CssValue;
+}
+/**
+ * Space scale - spacing tokens used throughout the design system.
+ */
+export interface SpaceScale {
+    none?: CssValue;
+    xxs?: CssValue;
+    xs?: CssValue;
+    s?: CssValue;
+    m?: CssValue;
+    l?: CssValue;
+    xl?: CssValue;
+    xxl?: CssValue;
+    [key: string]: CssValue | undefined;
+}
+/**
+ * Max width scale - responsive container widths.
+ */
+export interface MaxWidthScale {
+    xxs?: CssValue;
+    xs?: CssValue;
+    s?: CssValue;
+    m?: CssValue;
+    l?: CssValue;
+    xl?: CssValue;
+    xxl?: CssValue;
+    full?: CssValue;
+    [key: string]: CssValue | undefined;
+}
+/**
+ * Color palette - foreground, accent, and semantic colors.
+ * Cloud themes use either flat (Standard) or nested (CloudDark) structure.
+ */
+export interface ColorPalette {
+    /** Flat structure (Standard, CloudLight) */
+    base?: CssValue;
+    primary?: CssValue;
+    secondary?: CssValue;
+    accent?: CssValue;
+    info?: CssValue;
+    danger?: CssValue;
+    'alt-primary'?: CssValue;
+    'alt-secondary'?: CssValue;
+    /** Nested structure (CloudDark) */
+    foreground?: {
+        primary?: CssValue;
+        secondary?: CssValue;
+    };
+    [key: string]: CssValue | {
+        primary?: CssValue;
+        secondary?: CssValue;
+    } | undefined;
+}
+/**
+ * Surface definitions - base surface colors and gradients.
+ */
+export interface SurfaceDefinitions {
+    primary?: CssValue;
+    secondary?: CssValue;
+    base?: CssValue;
+    accent?: CssValue;
+    'radial-gradient'?: CssValue;
+    'linear-gradient'?: CssValue;
+    decorated?: CssValue;
+    [key: string]: CssValue | undefined;
+}
+/**
+ * Surfaces - named surface variants for components.
+ * Keys map to data-surface attribute values.
+ */
+export interface SurfacesMap {
+    base?: SurfaceVariant;
+    primary?: SurfaceVariant;
+    secondary?: SurfaceVariant;
+    decorated?: SurfaceVariant;
+    'alt-primary'?: SurfaceVariant;
+    'alt-secondary'?: SurfaceVariant;
+    'radial-gradient'?: SurfaceVariant;
+    'linear-gradient'?: SurfaceVariant;
+    'alt-glass'?: SurfaceVariant;
+    info?: SurfaceVariant;
+    danger?: SurfaceVariant;
+    accent?: SurfaceVariant;
+    [key: string]: SurfaceVariant | undefined;
+}
+/**
+ * Theme - the complete design system theme structure.
+ * Based on cloud-light and cloud-dark (the canonical themes).
+ */
+export interface Theme {
+    /** Spacing scale - maps to --space-* CSS variables */
+    space: SpaceScale;
+    /** Max width scale - maps to --max-width-* CSS variables */
+    'max-width': MaxWidthScale;
+    /** Color palette */
+    color?: ColorPalette;
+    /** Base surface definitions - maps to --surface-* */
+    surface: SurfaceDefinitions;
+    /** Surface variants - maps to [data-surface="key"] blocks */
+    surfaces: SurfacesMap;
+    /** Separator colors */
+    separator: CssStyleGroup;
+    /** Title/heading styles */
+    title: CssStyleGroup;
+    /** Body text styles */
+    text: CssStyleGroup;
+    /** Button variant styles */
+    button: CssStyleGroup;
+    /** Card variant styles */
+    card: CssStyleGroup;
+    /** Resume-specific styles */
+    resume?: CssStyleGroup;
+    /** Additional theme sections - allows extensibility */
+    [key: string]: SpaceScale | MaxWidthScale | CssStyleGroup | SurfacesMap | ColorPalette | SurfaceDefinitions | undefined;
+}
+/**
+ * Theme identifier - the canonical theme names.
+ */
+export type ThemeId = 'cloud-light' | 'cloud-dark';

package/build/types/{index.d.ts → src/index.d.ts}

@@ -1,4 +1,5 @@
 export type { Field } from './Field';
+export type { Theme, ThemeId, CssValue, CssStyleGroup, SurfaceVariant, SpaceScale, MaxWidthScale, ColorPalette, SurfaceDefinitions, SurfacesMap } from './Theme';
 export type { Resource } from './Resource';
 export type { ResourceTemplate } from './ResourceTemplate';
 export type { Workspace } from './Workspace';

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@ossy/types",
   "description": "Shared TypeScript types for all packages",
-  "version": "0.2.1",
+  "version": "0.3.1",
   "url": "git://github.com/ossy-se/packages/types",
   "source": "src/index.ts",
   "module": "build/index.js",
@@ -26,5 +26,5 @@
     "/build",
     "README.md"
   ],
-  "gitHead": "009330a43cf08e0cab806434b5f654401924af95"
+  "gitHead": "fa8cbcb5f24811e6844c929d7fa7cd1d2544efa7"
 }