@almadar/ui 1.0.0

package/LICENSE

@@ -0,0 +1,72 @@
+Business Source License 1.1
+
+Parameters
+
+Licensor:             Almadar FZE
+Licensed Work:        KFlow Builder / Almadar
+                      The Licensed Work is (c) 2025-2026 Almadar FZE.
+Additional Use Grant: You may make production use of the Licensed Work for
+                      non-commercial purposes and for internal evaluation.
+                      Production use for commercial purposes requires a
+                      commercial license from the Licensor.
+Change Date:          2030-02-01
+Change License:       Apache License, Version 2.0
+
+Terms
+
+The Licensor hereby grants you the right to copy, modify, create derivative
+works, redistribute, and make non-production use of the Licensed Work. The
+Licensor may make an Additional Use Grant, above, permitting limited
+production use.
+
+Effective on the Change Date, or the fourth anniversary of the first publicly
+available distribution of a specific version of the Licensed Work under this
+License, whichever comes first, the Licensor hereby grants you rights under
+the terms of the Change License, and the rights granted in the paragraph
+above terminate.
+
+If your use of the Licensed Work does not comply with the requirements
+currently in effect as described in this License, you must purchase a
+commercial license from the Licensor, its affiliated entities, or authorized
+resellers, or you must refrain from using the Licensed Work.
+
+All copies of the original and modified Licensed Work, and derivative works
+of the Licensed Work, are subject to this License. This License applies
+separately for each version of the Licensed Work and the Change Date may vary
+for each version of the Licensed Work released by Licensor.
+
+You must conspicuously display this License on each original or modified copy
+of the Licensed Work. If you receive the Licensed Work in original or
+modified form from a third party, the terms and conditions set forth in this
+License apply to your use of that work.
+
+Any use of the Licensed Work in violation of this License will automatically
+terminate your rights under this License for the current and all other
+versions of the Licensed Work.
+
+This License does not grant you any right in any trademark or logo of
+Licensor or its affiliates (provided that you may use a trademark or logo of
+Licensor as expressly required by this License).
+
+TO THE EXTENT PERMITTED BY APPLICABLE LAW, THE LICENSED WORK IS PROVIDED ON
+AN "AS IS" BASIS. LICENSOR HEREBY DISCLAIMS ALL WARRANTIES AND CONDITIONS,
+EXPRESS OR IMPLIED, INCLUDING (WITHOUT LIMITATION) WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, NON-INFRINGEMENT, AND
+TITLE.
+
+---
+
+License text copyright (c) 2017 MariaDB Corporation Ab, All Rights Reserved.
+"Business Source License" is a trademark of MariaDB Corporation Ab.
+
+ADDITIONAL TERMS:
+
+Documentation (builder/packages/website/docs/) is licensed under CC BY 4.0.
+
+TRADEMARKS:
+
+"Orbital", "KFlow", "Almadar", and the Almadar logo are trademarks of
+Almadar FZE. You may not use these trademarks without prior written
+permission from Almadar FZE.
+
+For licensing inquiries: licensing@almadar.io

package/README.md

@@ -0,0 +1,335 @@
+# Orbital Design System
+
+A themeable, domain-aware component library for Orbital applications. Generates client-specific design systems from `.orb` schemas.
+
+## Features
+
+- **CSS Variable-Based Theming**: All components use CSS variables, enabling easy theme switching
+- **Domain Detection**: Automatically detects domain (garden, healthcare, finance, etc.) from schema
+- **Component Suggestions**: Suggests domain-specific components based on schema analysis
+- **Storybook Integration**: Visual component documentation with theme switching
+- **Static Export**: Export design system as static HTML for client delivery
+
+## Quick Start
+
+```bash
+# Install dependencies
+npm install
+
+# Start Storybook for development
+npm run storybook
+
+# Generate a client-specific design system
+npm run generate path/to/schema.orb
+```
+
+## Available Themes
+
+| Theme | Description | Best For |
+|-------|-------------|----------|
+| `wireframe` | High contrast, sharp edges | Prototyping |
+| `minimalist` | Soft, elegant, subtle | Corporate apps |
+| `almadar` | Brand-specific styling | Al-Madar projects |
+| `winning-11` | Garden/organic theme | Agriculture, nature |
+
+## Scripts
+
+### `npm run storybook`
+Start Storybook development server on port 6006.
+
+### `npm run build-storybook`
+Build static Storybook documentation.
+
+### `npm run generate <schema.orb> [options]`
+Generate a complete client-specific design system.
+
+Options:
+- `--output <dir>` - Output directory (default: ./exports)
+- `--name <name>` - Client name override
+- `--no-storybook` - Skip Storybook build
+- `--no-components` - Skip component generation
+
+Example:
+```bash
+npm run generate ../architecture/winning-11.orb --output ./clients
+```
+
+### `npm run generate:theme <schema.orb> [output.css]`
+Generate only the theme CSS from a schema.
+
+### `npm run suggest:components <schema.orb> [--generate <dir>]`
+Analyze schema and suggest domain-specific components.
+
+## Component Library Structure
+
+```
+components/
+├── atoms/           # Basic building blocks
+│   ├── Button
+│   ├── Input
+│   ├── Badge
+│   ├── Card
+│   └── ...
+├── molecules/       # Composite components
+│   ├── Alert
+│   ├── Modal
+│   ├── Tabs
+│   └── ...
+├── organisms/       # Complex components
+│   ├── DataTable
+│   ├── Header
+│   ├── Sidebar
+│   └── ...
+└── templates/       # Page layouts
+    ├── AuthLayout
+    ├── FormTemplate
+    └── ...
+```
+
+## Theming
+
+### Using a Theme
+
+Apply a theme by setting `data-design-theme` attribute:
+
+```html
+<html data-design-theme="winning-11">
+  ...
+</html>
+```
+
+Or in React:
+
+```tsx
+<div data-design-theme="winning-11">
+  <Button>Themed Button</Button>
+</div>
+```
+
+### CSS Variables
+
+All components use CSS variables for theming:
+
+```css
+/* Colors */
+--color-primary
+--color-primary-hover
+--color-primary-foreground
+--color-secondary
+--color-secondary-foreground
+--color-accent
+--color-muted
+--color-muted-foreground
+--color-background
+--color-foreground
+--color-border
+
+/* Shadows */
+--shadow-sm
+--shadow-main
+--shadow-lg
+--shadow-hover
+
+/* Border Radius */
+--radius-sm
+--radius-md
+--radius-lg
+--radius-xl
+
+/* Transitions */
+--transition-fast
+--transition-normal
+--transition-slow
+```
+
+### Creating a Custom Theme
+
+1. Create a CSS file in `themes/`:
+
+```css
+[data-design-theme="my-theme"] {
+    --color-primary: #your-color;
+    --color-secondary: #your-color;
+    /* ... other variables */
+}
+```
+
+2. Import in `themes/index.css`:
+
+```css
+@import './my-theme.css';
+```
+
+3. Add to Storybook preview (`.storybook/preview.tsx`):
+
+```tsx
+themes: {
+  // ...existing themes
+  'my-theme': 'my-theme',
+}
+```
+
+## Domain-Specific Components
+
+The generator suggests domain-specific components based on schema analysis:
+
+### Garden/Agriculture Domain
+- `GardenView` - Visual garden layout
+- `PlantCard` - Plant display with care indicators
+- `GrowthMeter` - Progress indicator for growth
+- `TrustMeter` - Trust/relationship indicator
+- `CareIndicator` - Water/sun/nutrient needs
+
+### Healthcare Domain
+- `PatientCard` - Patient information display
+- `VitalsDisplay` - Vital signs compact view
+- `AppointmentSlot` - Scheduling component
+
+### E-commerce Domain
+- `ProductCard` - Product with price and cart action
+- `CartSummary` - Cart overview
+- `PriceTag` - Formatted price display
+
+### Game Domain
+- `CharacterStats` - RPG-style stat display
+- `QuestTracker` - Active quest panel
+
+## Integration with Proposal Documents
+
+The generated design system can be included in client proposals:
+
+1. Generate the design system:
+   ```bash
+   npm run generate ../architecture/winning-11.orb --output ./exports
+   ```
+
+2. The export includes:
+   - Theme CSS file
+   - Component stubs (if domain detected)
+   - Storybook documentation
+   - Manifest with metadata
+
+3. Reference in proposal documents or deliver as standalone package.
+
+## Client-Specific Components
+
+Client-specific components live in dedicated folders named after the client. These components:
+- **Extend the core library** - Use existing atoms/molecules, don't recreate them
+- **Follow Atomic Design** - Break down into atoms, molecules, organisms, templates
+- **Include Storybook stories** - Every component must have a `.stories.tsx` file
+- **Are reusable** - Can be used in future projects for the same client
+
+### Directory Structure
+
+```
+orbital-shared/design-system/
+├── components/              # Core component library (shared across all clients)
+│   ├── atoms/
+│   ├── molecules/
+│   ├── organisms/
+│   └── templates/
+├── clients/                 # Client-specific components
+│   ├── winning-11/          # Winning-11 client
+│   │   ├── atoms/           # Client-specific atoms (rare)
+│   │   ├── molecules/       # Client-specific molecules
+│   │   ├── organisms/       # Client-specific organisms
+│   │   ├── templates/       # Client page templates/showcases
+│   │   └── index.ts         # Barrel export
+│   └── [other-client]/      # Another client folder
+└── ...
+```
+
+### When to Create Client-Specific Components
+
+| Scenario | Where to Add |
+|----------|--------------|
+| Generic component useful for any project | `components/` (core library) |
+| Domain-specific styling of existing component | Client folder with composition |
+| Unique business logic component | Client folder |
+| Page template/showcase | `clients/[name]/templates/` |
+
+### Creating Client-Specific Components
+
+1. **Create in client folder**:
+   ```
+   clients/winning-11/organisms/GardenLayout.tsx
+   clients/winning-11/organisms/GardenLayout.stories.tsx
+   ```
+
+2. **Import from core library**:
+   ```tsx
+   import { Card, Badge } from '../../../components/atoms';
+   import { Grid } from '../../../components/molecules';
+   ```
+
+3. **Export from client index**:
+   ```tsx
+   // clients/winning-11/index.ts
+   export * from './organisms/GardenLayout';
+   ```
+
+4. **Create Storybook story**:
+   ```tsx
+   // GardenLayout.stories.tsx
+   import type { Meta, StoryObj } from '@storybook/react';
+   import { GardenLayout } from './GardenLayout';
+
+   const meta: Meta<typeof GardenLayout> = {
+     title: 'Clients/Winning-11/Organisms/GardenLayout',
+     component: GardenLayout,
+   };
+   export default meta;
+   ```
+
+### Client Templates
+
+Templates showcase complete page layouts specific to the client. They demonstrate:
+- How components compose together
+- Realistic data patterns
+- Brand-specific styling
+
+```tsx
+// clients/winning-11/templates/GardenDashboard.tsx
+export const GardenDashboard = () => (
+  <PageLayout>
+    <Header />
+    <GardenStats />
+    <PlantGrid plants={mockPlants} />
+  </PageLayout>
+);
+```
+
+### Syncing to Projects
+
+When generating a client project, client-specific components are copied:
+
+```bash
+npm run generate schema.orb --client winning-11 --output ../projects/winning-11
+```
+
+This copies:
+- Core `components/` library
+- Client-specific `clients/winning-11/` folder
+- Themes and hooks
+
+## Development
+
+### Adding New Components
+
+1. Create component in appropriate category (`atoms/`, `molecules/`, `organisms/`)
+2. Create corresponding `.stories.tsx` file
+3. Export from category's `index.ts`
+4. Verify in Storybook
+
+### Adding New Themes
+
+1. Create theme CSS in `themes/`
+2. Follow existing theme structure for CSS variables
+3. Add import to `themes/index.css`
+4. Add to Storybook theme selector
+
+### Adding Domain-Specific Components
+
+1. Add domain config to `scripts/suggest-components.ts`
+2. Define keywords and component suggestions
+3. Test with schema from that domain

package/dist/ThemeContext-lI5bo85E.d.ts

@@ -0,0 +1,103 @@
+import React__default from 'react';
+
+/**
+ * Unified ThemeContext - Single provider for theme and color mode
+ *
+ * Combines design theme selection (ocean, wireframe, etc.) with
+ * color mode (light/dark) into a single, simple system.
+ *
+ * Uses a single data attribute: data-theme="ocean-light" or data-theme="ocean-dark"
+ *
+ * @packageDocumentation
+ */
+
+/** Color mode preference */
+type ColorMode = "light" | "dark" | "system";
+/** Resolved color mode (what's actually applied) */
+type ResolvedMode = "light" | "dark";
+/** Theme definition */
+interface ThemeDefinition {
+    /** Theme identifier (e.g., "ocean", "wireframe") */
+    name: string;
+    /** Display name for UI (e.g., "Ocean Blue") */
+    displayName?: string;
+    /** Whether this theme has light mode styles */
+    hasLightMode?: boolean;
+    /** Whether this theme has dark mode styles */
+    hasDarkMode?: boolean;
+}
+/** Built-in themes available in the design system */
+declare const BUILT_IN_THEMES: ThemeDefinition[];
+/** Theme context value */
+interface ThemeContextValue {
+    /** Current theme name */
+    theme: string;
+    /** Current color mode setting (may be 'system') */
+    mode: ColorMode;
+    /** Resolved color mode (always 'light' or 'dark') */
+    resolvedMode: ResolvedMode;
+    /** Set the theme */
+    setTheme: (theme: string) => void;
+    /** Set the color mode */
+    setMode: (mode: ColorMode) => void;
+    /** Toggle between light and dark modes */
+    toggleMode: () => void;
+    /** Available themes */
+    availableThemes: ThemeDefinition[];
+    /** The full theme string applied to data-theme (e.g., "ocean-light") */
+    appliedTheme: string;
+}
+declare const ThemeContext: React__default.Context<ThemeContextValue | undefined>;
+interface ThemeProviderProps {
+    children: React__default.ReactNode;
+    /** Available themes (will be merged with built-in themes) */
+    themes?: readonly ThemeDefinition[] | ThemeDefinition[];
+    /** Default theme name */
+    defaultTheme?: string;
+    /** Default color mode */
+    defaultMode?: ColorMode;
+}
+/**
+ * Unified ThemeProvider component
+ *
+ * @example
+ * ```tsx
+ * // Basic usage with built-in themes
+ * <ThemeProvider defaultTheme="wireframe" defaultMode="light">
+ *   <App />
+ * </ThemeProvider>
+ *
+ * // With custom themes from orbital schema
+ * import { THEMES } from './generated/theme-manifest';
+ * <ThemeProvider themes={THEMES} defaultTheme="ocean" defaultMode="system">
+ *   <App />
+ * </ThemeProvider>
+ * ```
+ */
+declare const ThemeProvider: React__default.FC<ThemeProviderProps>;
+/**
+ * Hook for accessing theme context
+ *
+ * @returns Theme context value
+ *
+ * @example
+ * ```tsx
+ * const { theme, resolvedMode, toggleMode, setTheme } = useTheme();
+ *
+ * // Toggle dark mode
+ * <button onClick={toggleMode}>
+ *   {resolvedMode === 'dark' ? 'Light' : 'Dark'}
+ * </button>
+ *
+ * // Change theme
+ * <select value={theme} onChange={(e) => setTheme(e.target.value)}>
+ *   {availableThemes.map(t => (
+ *     <option key={t.name} value={t.name}>{t.displayName || t.name}</option>
+ *   ))}
+ * </select>
+ * ```
+ */
+declare function useTheme(): ThemeContextValue;
+type DesignTheme = ThemeDefinition;
+
+export { BUILT_IN_THEMES as B, type ColorMode as C, type DesignTheme as D, type ResolvedMode as R, type ThemeProviderProps as T, ThemeContext as a, type ThemeDefinition as b, ThemeProvider as c, useTheme as u };