@widgetic/design-system 0.3.68

package/README.md

@@ -0,0 +1,730 @@
+# Widgetic Design System
+
+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';
+```
+
+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.
+
+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,
+};
+```
+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';
+```
+
+
+3. Fonts: The design system uses Google Fonts that we need to import in the project where the design system is imported.
+
+```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:
+
+```json
+"dependencies": {
+"tailwindcss": "^3.4.16",
+"@tailwindcss/postcss": "^4.1.2",
+}
+```
+
+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"
+	},
+```
+
+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';
+
+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...
+		}
+	}
+};
+
+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.
+
+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';
+</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.
+
+
+
+## Developing inside this project:
+
+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;
+  }
+}
+```
+
+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>
+```
+
+
+### Create a Custom Shared Component in the Design System project using a SHADCN UI component and classes from the global styles:
+
+src/lib/components/MyButton.svelte:
+```svelte
+<script>
+  <!-- Import Button from the SHADCN UI components -->
+  import { Button } from './components/ui';
+</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';
+```
+
+
+## Deployment of Design System
+
+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
+```
+
+## Grid System
+
+The design system implements three distinct responsive grid layouts:
+
+1. Site Grid
+2. Dashboard Grid
+3. App Grid
+
+### Grid Breakpoints
+- Desktop: > 744px
+- Tablet: 393px - 744px
+- Mobile: ≤ 393px
+
+### 1. Site Grid
+
+**Desktop (>744px)**
+- 12 columns
+- 144px margins
+- 24px gutters
+- Stretching columns with auto width
+
+**Tablet (≤744px)**
+- 8 columns
+- 32px margins
+- 16px gutters
+- Stretching columns with auto width
+
+**Mobile (≤393px)**
+- 4 columns
+- 16px margins
+- 16px gutters
+- Stretching columns with auto width
+
+### 2. Dashboard Grid
+
+**Desktop (>744px)**
+- Header: 12 columns, 24px margins, 20px gutters
+- Sidebar: 240px fixed width
+- Main Content: 12 columns, 24px margins, 20px gutters
+- 56px header height
+
+**Tablet (≤744px)**
+- Header: 8 columns
+- Sidebar: 200px fixed width
+- Main Content: 8 columns
+- 16px margins and gutters
+
+**Mobile (≤393px)**
+- Header: 4 columns
+- Sidebar replaced with menu component
+- Main Content: 4 columns
+- 16px margins and gutters
+
+### 3. App Grid
+
+**Desktop (>744px)**
+- Header: 12 columns, 24px margins, 20px gutters
+- Main Content: 12 columns, 144px margins, 20px gutters
+- 56px header height
+
+**Tablet (≤744px)**
+- Header: 8 columns
+- Main Content: 8 columns, 32px margins
+- 16px gutters
+
+**Mobile (≤393px)**
+- Header: 4 columns
+- Menu component added below header
+- Main Content: 4 columns
+- 16px margins and gutters
+
+### Usage Example
+
+```svelte
+<!-- Site Grid -->
+<div class="site-grid">
+  <div class="grid-margin-left"></div>
+  <header class="grid-header">Header Content</header>
+  <main class="grid-main">Main Content</main>
+  <footer class="grid-footer">Footer Content</footer>
+  <div class="grid-margin-right"></div>
+</div>
+
+<!-- Dashboard Grid -->
+<div class="dashboard-grid">
+  <div class="grid-margin-left"></div>
+  <header class="dashboard-header-grid">
+    <!-- Header content with 12/8/4 columns based on viewport -->
+  </header>
+  <nav class="grid-sidebar">
+    <!-- Sidebar content (hidden on mobile) -->
+  </nav>
+  <main class="dashboard-main-grid">
+    <!-- Main content with 12/8/4 columns based on viewport -->
+  </main>
+  <div class="grid-margin-right"></div>
+  <!-- Mobile menu appears automatically on small screens -->
+  <div class="grid-menu">
+    <!-- Mobile menu content -->
+  </div>
+</div>
+
+<!-- App Grid -->
+<div class="app-grid">
+  <div class="grid-margin-left"></div>
+  <header class="app-header-grid">
+    <!-- Header content with 12/8/4 columns based on viewport -->
+  </header>
+  <main class="app-main-grid">
+    <!-- Main content with 12/8/4 columns based on viewport -->
+  </main>
+  <div class="grid-margin-right"></div>
+  <!-- Mobile menu appears automatically on small screens -->
+  <div class="grid-menu">
+    <!-- Mobile menu content -->
+  </div>
+</div>
+```
+
+### Grid Area Classes
+The following classes are available to position elements within the grid:
+```css
+.grid-header      /* Header area */
+.grid-main        /* Main content area */
+.grid-sidebar     /* Sidebar area (dashboard only) */
+.grid-footer      /* Footer area (site only) */
+.grid-toolbar     /* Toolbar area (app only) */
+.grid-margin-left /* Left margin area */
+.grid-margin-right/* Right margin area */
+.grid-menu        /* Mobile menu area */
+.grid-gap         /* Gap area (dashboard only) */
+```
+
+The grid system is designed to maintain consistent spacing and layout across different viewport sizes while adapting to the specific needs of each layout type (site, dashboard, and app).
+
+## DeleteConfirmation Component
+
+The `DeleteConfirmation` component is a reusable confirmation dialog that can be used across different parts of the project for confirming deletion actions.
+
+### Features
+
+- Independent of any specific store or state management system
+- Customizable title, message, and button labels
+- Works with any type of items to be deleted
+- Dispatches events for both confirmation and cancellation
+
+### Usage
+
+```svelte
+<script>
+  import { DeleteConfirmation } from '@widgetic/design-system/components';
+  
+  let showDeleteConfirmation = false;
+  let itemsToDelete = [
+    { id: '1', name: 'Document.pdf', type: 'file' },
+    { id: '2', name: 'Images', type: 'folder' }
+  ];
+  
+  function handleDelete(event) {
+    const deletedItems = event.detail.items;
+    console.log('Items to delete:', deletedItems);
+    // Perform deletion logic here
+  }
+  
+  function handleCancel() {
+    showDeleteConfirmation = false;
+    console.log('Deletion cancelled');
+  }
+</script>
+
+<button on:click={() => showDeleteConfirmation = true}>
+  Delete Items
+</button>
+
+<DeleteConfirmation
+  bind:isOpen={showDeleteConfirmation}
+  items={itemsToDelete}
+  modalId="my-delete-confirmation"
+  on:delete={handleDelete}
+  on:cancel={handleCancel}
+/>
+```
+
+### Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `isOpen` | boolean | `false` | Controls the visibility of the modal |
+| `items` | array | `[]` | Array of items to be deleted |
+| `title` | string | `''` | Custom title for the modal (autogenerated if empty) |
+| `message` | string | `''` | Custom message for the modal (autogenerated if empty) |
+| `confirmLabel` | string | `'Confirm'` | Label for the confirm button |
+| `cancelLabel` | string | `'Cancel'` | Label for the cancel button |
+| `width` | string | `'410px'` | Width of the modal |
+| `height` | string | `'168px'` | Height of the modal |
+| `modalId` | string | `'delete-confirmation-modal'` | ID for targeting the modal |
+
+### Events
+
+- `delete` - Dispatched when the user confirms deletion, with `items` in the event detail
+- `cancel` - Dispatched when the user cancels deletion
+
+### Custom Title and Message Example
+
+You can provide custom title and message for specific contexts:
+
+```svelte
+<script>
+  import { DeleteConfirmation } from '@widgetic/design-system/components';
+  
+  let showDeleteConfirmation = false;
+  let selectedItems = [
+    { id: '1', name: 'Document.pdf', type: 'file' },
+    { id: '2', name: 'Images', type: 'folder' }
+  ];
+  
+  function handleDelete(event) {
+    const deletedItems = event.detail.items;
+    console.log('Items to delete:', deletedItems);
+    // Perform deletion logic here
+  }
+  
+  function handleCancel() {
+    showDeleteConfirmation = false;
+    console.log('Deletion cancelled');
+  }
+</script>
+
+<DeleteConfirmation 
+  bind:isOpen={showDeleteConfirmation}
+  items={selectedItems}
+  title="Delete Assets"
+  message="These assets will be permanently deleted. This action cannot be undone."
+  confirmLabel="Delete Permanently"
+  on:delete={handleDelete}
+  on:cancel={handleCancel}
+/>
+```