@widgetic/design-system 0.3.68 → 0.3.71

package/README.md

@@ -1,493 +1,165 @@
-# Widgetic Design System
+# Widgetic Design System (`@widgetic/design-system`)
+
+This is the official design system package for the Widgetic platform.
+
+Built with SvelteKit and Tailwind CSS (using shadcn-svelte components as a base), it provides reusable UI components, global styles, design tokens, icons, and fonts for building consistent interfaces across Widgetic projects.
+
+## Features
+
+*   **Styles:** Exports global CSS styles, including CSS variables for design tokens (colors, spacing, etc.) and utility classes based on Tailwind CSS v4.
+*   **UI Components:** A library of Svelte components built upon [shadcn-svelte](https://shadcn-svelte.com/), providing elements like Buttons, Cards, Dialogs, Input fields, Accordions, etc. Includes both base shadcn components and custom Widgetic components.
+*   **Icons:** Exports icons from [Lucide Svelte](https://lucide.dev/) and potentially [Tabler Icons](https://tabler-icons.io/), accessible via named imports.
+*   **Fonts:** Includes specific font families used across the Widgetic platform. Font files themselves are exported, but consuming projects need to ensure they are loaded correctly (e.g., via CSS `@import` or `<link>`).
+
+## Installation
+
+1.  **Install the package:**
+    ```bash
+    npm install @widgetic/design-system
+    ```
+
+2.  **Install Peer Dependencies:** This package relies on several peer dependencies that you need to install in your project if you haven't already. Ensure your `package.json` includes compatible versions:
+    ```json
+    "devDependencies": {
+      // Required by Tailwind v4 setup
+      "postcss": "^8.x.x",
+      "@tailwindcss/postcss": "^4.x.x", 
+      "tailwindcss": "^4.x.x", 
+      // Required by SvelteKit/Svelte 5
+      "svelte": "^5.x.x",
+      "@sveltejs/kit": "^2.x.x",
+      // Required by shadcn-svelte components used internally
+      "bits-ui": "^1.x.x",
+      "clsx": "^2.x.x",
+      "tailwind-merge": "^2.x.x",
+      "tailwind-variants": "^0.x.x",
+      "svelte-sonner": "^0.x.x",
+      // Required by specific components if used
+      "@internationalized/date": "^3.x.x",
+      "lucide-svelte": "^0.x.x",
+      "@tabler/icons-svelte": "^3.x.x",
+      "vaul-svelte": "^1.x.x-next.x"
+      // ... other project devDependencies
+    }
+    ```
+    *Note: Replace `x.x` with appropriate version numbers compatible with the design system's requirements (check its `package.json` `peerDependencies` for specifics).* Make sure you have `postcss.config.js` (or `.mjs`) set up.
+
+## Setup
+
+### 1. Tailwind Configuration
+
+To ensure Tailwind processes the design system's classes and applies your project's customizations correctly, configure your project's `tailwind.config.ts` (or `.js`) to use the design system's configuration as a preset:
 
-This is the design system package for the Widgetic platform.
-
-It is built with SvelteKit and TailwindCSS and exports styles(with tailwind), ui components(with shadcn), icons and fonts for the entire platform.
-
-0. Styles: it uses tailwindcss and exports global styles and design tokens that are imported in the project where the design system is imported:
-
-```svelte
-<script>
-  import '@widgetic/design-system/styles';
-</script>
-```
-
-0.1. To add new fonts: 
-- Add the font in the fonts folder.
-- Add the font-face rule and the class in the fonts.css file and then the class can be used anywhere in the projects that import the design system's styles:
-```css
- /* First font-face rule */
-  @font-face {
-    font-family: 'BL Melody';
-    src: url('@widgetic/design-system/fonts/BLMelody/BLMelody-ExtraLight.woff2') format('woff2');
-    font-weight: 200;
-    font-style: normal;
-    font-display: swap;
-  }
-  
-  /* Second fonte class(can be any custom name) */
-  .font-bl-melody-extra-light {
-    font-family: 'BL Melody';
-    font-weight: 200;
-  }
-```
-
-- Use the font-family in any class in the global.css file if needed like this:
-```css
-.my-button-class {
-  /* other CSS properties */
-  background-color: red;
-
-  /* font-family properties here */
-  font-family: 'BL Melody', sans-serif;
-  font-weight: 200;
-  font-style: normal;
-}
-```
-
-1.1. Components: It uses the SHADCN UI components for basic ui components and custom components for the Widgetic platform.
-
-a. (Re)Install latest all shadcn components:
-
-```bash
-npm run i-shadcn
-```
-
-At prompt answer like this:
-```bash
-Which style would you like to use?
-│  Default
-│
-◇  Which base color would you like to use?
-│  Slate
-│
-◇  Where is your global CSS file? (this file will be overwritten)
-│  src/app.css (!!! add local project's css file as we don't want to overwrite our project's global styles)
-│
-◇  Where is your Tailwind config located? (this file will be overwritten)
-│  tailwind.config.ts
-│
-◇  Configure the import alias for components:
-│  $lib/components
-│
-◆  Configure the import alias for utils:
-│  $lib/utils
-│
-◆  Configure the import alias for hooks:
-│  $lib/hooks
-│
-◆  Configure the import alias for ui:
-│  $lib/components/ui
-
-
-Components to install:
-│  accordion, badge, button, calendar, range-calendar, card, checkbox, collapsible, dialog,
-│  drawer, dropdown-menu, input, input-otp, label, popover, progress, radio-group, scroll-area,
-│  select, separator, slider, switch, table, tabs, textarea, tooltip
-│
-◆  Ready to install components and dependencies?
-│  ● Yes / ○ No
-...
-tooltip installed at src/lib/components/ui/tooltip
-│
-◇  Dependencies installed with npm
-│
-◇  Config file components.json updated
-│
-└  Success! Component installation completed.
-
-!!! On commit the change uncheck the grouped components(Table, Select, etc.) baerel file.
-```
-
-b. Installing the shadcn-svelte package:
-
-```bash
-npx shadcn-svelte@next init
-```
-
-c. Add one or more SHADCN UI components:
-
-```bash
-npx shadcn-svelte@next add <component-name component-name2>
-```
-
-d. Check tailwind.config.ts file to see if you didn't lose any of the project's config.
-
-e. Check /src/lib/utils/utils.ts file to see if you didn't lose any of the project's utils.
-
-f. Check /src/lib/hooks/hooks.ts file to see if you didn't lose any of the project's hooks.
-
-g. Check SHADCN UI Grouped components(eg. Table or Select) barel file to export a constant with the subcomponents.
-We do that just be wrapping the first part of the export statement with a constant named as the component ("Table" here) and replace the exported subcomponent: "Table" in this case with "TableRoot".
 ```ts
-// src/lib/components/ui/table/index.ts
-const Table = {
-	Root,
-	Body,
-	Caption,
-	Cell,
-	Footer,
-	Head,
-	Header,
-	Row
-};
-
-export {
-	Table, // add the constant name "Table" that will be the namespace for the grouped components
-	Root as TableRoot, // Change the name of the Root component from "Table" to "TableRoot"
-	Body as TableBody,
-	Caption as TableCaption,
-	Cell as TableCell,
-	Footer as TableFooter,
-	Head as TableHead,
-	Header as TableHeader,
-	Row as TableRow,
-};
-```
-Then you can import and use the namespace in the project:
-```svelte
-import { Table } from '@widgetic/design-system';
-```
+// tailwind.config.ts
+import type { Config } from 'tailwindcss';
+import designSystemPreset from '@widgetic/design-system/tailwind.config'; // Import the preset
 
-h. If there is a component that looks compound but is not, add the @notCompound marker in the file:
-```ts
-// @notCompound
-export {
-	Root,
-	Scrollbar,
-	//,
-	Root as ScrollArea,
-	Scrollbar as ScrollAreaScrollbar,
-};
-```
-ScrollArea is not a compound component but it looks like one.
+const config = {
+    // Use the design system preset
+    presets: [designSystemPreset],
+
+    // Add your project's paths AND the design system's path to the content array
+    content: [
+        './src/**/*.{html,js,svelte,ts}', // Your project files
+        './node_modules/@widgetic/design-system/dist/**/*.{html,js,svelte,ts}' // Design system package files
+    ],
+
+    // You can optionally extend the theme further here
+    theme: {
+        extend: {
+            // Your project-specific theme extensions
+        }
+    },
+
+    plugins: [
+        // Your project-specific plugins (if any)
+    ]
+} satisfies Config;
 
-h. If you want to export only the main component and not the subcomponents, add the @noSubcomponents marker in the file:
-```ts
-// @noSubcomponents
-export {
-	Day,
-	Cell,
-	Grid,
-	Header,
-	Months,
-	GridRow,
-	Heading,
-	GridBody,
-	GridHead,
-	HeadCell,
-	NextButton,
-	PrevButton,
-	//
-	Root as RangeCalendar,
-};
+export default config;
 ```
-RangeCalendar share the same subcomponents with Calendar so we don't want to export them.
-
-1.2. In general we should follow the shadcn-svelte approach to export the components with more subcomponents or compound components.
 
-2. Icons: It also uses the Lucide and Tabler icons or custom icons for the platform.
-
-```svelte
-import { IconName } from '@widgetic/design-system/icons';
-```
+*   **Presets:** The `presets` array applies the design system's base configuration (colors, fonts, plugins like `tailwindcss-animate`).
+*   **Content:** It's crucial to include the path to the installed design system package (`./node_modules/@widgetic/design-system/dist/...`) in your `content` array. This allows Tailwind to scan the design system's components and generate the necessary utility classes.
 
+### 2. Global Styles
 
-3. Fonts: The design system uses Google Fonts that we need to import in the project where the design system is imported.
+Import the design system's global CSS file into your main layout file (e.g., `src/routes/+layout.svelte`). This file includes base styles, CSS variables (design tokens), and imports necessary fonts.
 
 ```svelte
-import { FontName } from '@widgetic/design-system/fonts';
-```
-
-
-## Performance Optimization for Linked Design System
-
-When using the linked design system in development mode, you may experience slow initial load times and delayed navigation. This is because Vite's default file watching behavior can create performance issues when working with linked packages.
-
-### Common Issues:
-- Long initial loading time (>1 minute)
-- "Pending" status on network requests when navigating between pages
-- High CPU usage during development
-
-### Solution:
-
-#### 1. For consuming projects (like site, context-chat, etc.):
-
-Optimize your `vite.config.ts` with these settings:
-
-```ts
-server: {
-  watch: {
-    // Don't use polling (which causes high CPU usage)
-    // Remove the following if present:
-    // usePolling: true,
-    // interval: 2000,
-    // binaryInterval: 2000,
-    
-    // Ignore all node_modules EXCEPT the design system dist folder if needed
-    ignored: [
-      '**/node_modules/**',
-      '**/*.map',
-      '**/*.d.ts',
-      '**/*.log'
-    ]
-  },
-  hmr: {
-    // Reduce timeout for faster updates
-    timeout: 2000
-  }
-},
-optimizeDeps: {
-  // Don't include the design system in optimizeDeps
-  // Remove this if present:
-  // include: ['@widgetic/design-system']
-  
-  // Keep other settings
-  exclude: ['@sveltejs/kit']
-},
-build: {
-  // Add these for faster builds
-  sourcemap: false,
-  reportCompressedSize: false
-}
-```
-
-#### 2. For production deployments:
-
-When deploying to production, you'll use the published npm package instead of the linked development version. No special configuration is needed beyond the optimizations above.
-
-#### 3. Development vs. Production Mode:
-
-The design system's `vite.config.ts` already includes development-specific optimizations. When publishing the package to npm, the built version will be used, and these configurations won't affect end users.
-
-**Note:** These optimizations are only needed during development with linked packages and won't affect the published npm package performance.
-
-
-## How to link DS into another project and develop it(first time)
-
-0. Go into the DS project and link it in the system and start it with: `cd Frontend/design-system && npm link && npm run dev`
-
-1. Go into the consuming project and make sure you have installed tailwindcss and postcss by checking in package.json if it has these dependencies:
+<!-- src/routes/+layout.svelte -->
+<script>
+  import '@widgetic/design-system/styles'; // Import global styles
 
-```json
-"dependencies": {
-"tailwindcss": "^3.4.16",
-"@tailwindcss/postcss": "^4.1.2",
-}
-```
+  // Your layout script...
+</script>
 
-Also make sure you have a 'tailwind.config.ts'(if there is a '.js' version rename it to '.ts') and a 'postcss.config.js' file.
-(optional)If not already in the project follow the install guide at: https://tailwindcss.com/docs/installation/using-postcss.
-
-
-2. Also add these dependencies and overrides(that are needed for DS) with these exact versions into the package.json file of the consuming project:
-```json package.json
-"dependencies": {
-    "@sveltejs/kit": "^2.20.2",
-		"svelte": "^5.25.6",
-		"@tabler/icons-svelte": "^3.24.0",
-		"lucide-svelte": "^0.468.0",
-		"bits-ui": "^1.3.0",
-    "svelte-sonner": "^0.3.28",
-
-    "tailwind-merge": "^2.5.2",
-		"tailwind-variants": "^0.2.1",
-		"tailwindcss-animate": "^1.0.7",
-}
-
-"overrides": {
-		"bits-ui": {
-			"@melt-ui/svelte": "^0.86.3"
-		},
-		"vaul-svelte": {
-			"bits-ui": {
-				"@melt-ui/svelte": "^0.86.3"
-			}
-		},
-    "svelte": "^5.25.6"
-	},
+<slot />
 ```
 
-Also keep the exact versions mentioned above and check and remove these dependencies from devDependencies or peerDependencies in the package.json of the consuming project.
-
-3. Also add this "i"(install) and "lds"(link) scripts into the package.json file exactly as following:
-"i": "rm -rf node_modules && npm i && npm run lds",
-"lds": "volta run npm link @widgetic/design-system",
-Then run it with: `npm run i`
-
-4. Also add these "dev" scripts into the package.json file for usual start of the consuming project:
-"dev": "npm run dev-sv -- --open",
-"dev-sv": "NODE_ENV=development vite dev",
-
-5. Import DS config into the tailwind.config.ts file(of consuming project) and add it in the presets array:
-```ts
-// tailwind.config.ts
-
-import designSystemPreset from '@widgetic/design-system/tailwind.config';
+## Usage
 
-const config = {
-  // add here the DS preset
-	presets: [
-		designSystemPreset
-	],
-  // add here the '@widgetic/*/dist/...' to scan also the DS package files
-	content: [
-		"./src/**/*.{html,js,svelte,ts}",
-		// Include all @widgetic packages from node_modules(for development only) to be sure Tailwind scans all the files
-		"./node_modules/@widgetic/*/dist/**/*.{html,js,svelte,ts}"
-	],
-  // the rest of the config properties
-	theme: {
-		extend: {
-      // current extend config...
-		}
-	}
-};
+### Components
 
-export default config;
-```
-Also make sure you remove the type of the config to avoid conflicts with the DS config.
-Then leave the rest of the config as it is.
+Import components directly from the package:
 
-6. Import styles and a test component from DS in the consuming project:
-a. In the root layout of the project import the global styles:
 ```svelte
-<!-- +layout.svelte -->
 <script>
-  import '@widgetic/design-system/styles';
+  import { Button, Card, CardHeader, CardTitle, CardContent } from '@widgetic/design-system';
+  // For grouped components (like Table, Accordion), use the namespace
+  import { Table } from '@widgetic/design-system';
 </script>
-```
-b. In the root page of the consuming project import any component(e.g. Button) and use it:
-```svelte
-<!-- +page.svelte -->
-<script>
-  import { Button } from '@widgetic/design-system/';
-</script>
-
-<!-- HTML zone -->
-<Button>Click me</Button>
-```
-
-7. Finally: go into the in the consuming project's folder and start the development server with:
-```bash
-npm run dev
-```
-
-This automatically opens the http://localhost:5173 (default port) for the consuming project and you can see how DS components work in it.
-
 
+<Button>Click Me</Button>
 
-## Developing inside this project:
+<Card.Root>
+  <Card.Header>
+    <Card.Title>Card Title</Card.Title>
+  </Card.Header>
+  <Card.Content>
+    <p>Card body content...</p>
+  </Card.Content>
+</Card.Root>
 
-1. Install dependencies with `npm install`
-
-2. Link the package in the system with npm:
-```bash
-npm link
-```
-
-3. Start the development server with:
-```bash
-npm run dev
-```
-
-3. Test the design system in action:
-- In the root layout of the DS project there is a global styles import to test the design system's global styles.
-- In the root page of the project there is a button component import to test the design system's components.
-
-Open in new tab in browser with address: http://localhost:5173/ to see the design system in action.
-
-
-
-### Global Tailwind CSS and Design Tokens:
-
-```css
-/* src/lib/styles/global.css */
-@tailwind base;
-@tailwind components;
-@tailwind utilities;
-
-/* CUSTOM GLOBAL STYLES */
-/* ADD HERE CLASSES AND CSS VARIABLES that are used in the projects where the design system is imported */
-
-/* Base styles */
-@layer base {
-  :root {
-    /* Design tokens */
-    --color-primary: 30 158 210; /* RGB values for easier theming */
-    --color-secondary: 46 204 113;
-    --radius: 0.5rem;
-  }
-
-  /* Dark mode tokens */
-  .dark {
-    --color-primary: 100 200 255;
-    --color-secondary: 100 255 150;
-  }
-}
-
-/* Reusable component classes */
-@layer components {
-  .btn-primary {
-    @apply bg-[rgb(var(--color-primary))] text-white rounded-[var(--radius)];
-  }
-
-  .card {
-    @apply shadow-md rounded-lg p-4 bg-white dark:bg-gray-800;
-  }
-}
-
-/* Custom utility classes */
-@layer utilities {
-  .text-balance {
-    text-wrap: balance;
-  }
-}
+<Table.Root>
+  <Table.Header>
+    <Table.Row>
+      <Table.Head>Header 1</Table.Head>
+    </Table.Row>
+  </Table.Header>
+  <Table.Body>
+    <Table.Row>
+      <Table.Cell>Cell 1</Table.Cell>
+    </Table.Row>
+  </Table.Body>
+</Table.Root>
 ```
 
-2. In the project where the design system is imported:
-- Import the global styles in the +layout.svelte file:
-```svelte
-<script>
-  import '@widgetic/design-system/styles';
-</script>
-```
+Refer to the specific component documentation or source code for available props and variants.
 
+### Icons
 
-### Create a Custom Shared Component in the Design System project using a SHADCN UI component and classes from the global styles:
+Import required icons by name:
 
-src/lib/components/MyButton.svelte:
 ```svelte
 <script>
-  <!-- Import Button from the SHADCN UI components -->
-  import { Button } from './components/ui';
+  import { ChevronUp, IconSettings } from '@widgetic/design-system/icons'; // Example names
 </script>
 
-<MyButton 
-  {type}
-  class="btn-primary"
-  on:click
->
-  <slot />
-</MyButton>
-```
-Then export the component in the "src/lib/components/index.ts" file:
-```ts
-export {default as MyButton } from './components/MyButton.svelte';
+<button>
+  <ChevronUp class="size-4" /> Settings <IconSettings class="size-4" />
+</button>
 ```
 
+### Fonts & Typography
 
-## Deployment of Design System
+The global styles load the necessary `@font-face` rules. You can apply typography using standard Tailwind utility classes (e.g., `text-lg`, `font-semibold`) or the custom typography utility classes exported by the design system (defined in `fonts.css`, like `h1`, `body-medium`, `subtext`).
 
-To deploy the design system, run the following command:
-```bash
-npm run prepublishOnly
-```
-This will create a `dist` folder with the production build of the design system.
-
-To publish the design system to the npm registry, run the following command:
-```bash
-npm run publish-package
+```svelte
+<h1 class="h1">Main Title</h1>
+<p class="body-medium">This is body text.</p>
+<span class="subtext">Some smaller text.</span>
 ```
 
 ## Grid System