@flightlesslabs/dodo-ui 0.7.2 → 0.9.0

package/src/lib/stories/developer tools/components/UtilityButton/UtilityButton.stories.svelte

@@ -0,0 +1,30 @@
+<script module lang="ts">
+  import { defineMeta } from '@storybook/addon-svelte-csf';
+  import UtilityButton from './UtilityButton.svelte';
+  import type { StoryBookArgTypes } from '$lib/storybook-types.js';
+  import Icon from '@iconify/svelte';
+  import { componentSizeArray } from '$lib/types/size.js';
+
+  export const storyUtilityButtonArgTypes: StoryBookArgTypes = {
+    size: {
+      control: { type: 'select' },
+      options: componentSizeArray,
+    },
+  };
+
+  // More on how to set up stories at: https://storybook.js.org/docs/writing-stories
+  const { Story } = defineMeta({
+    component: UtilityButton,
+    tags: ['autodocs'],
+    argTypes: storyUtilityButtonArgTypes,
+  });
+</script>
+
+<!-- Button with default style -->
+<Story name="Default">
+  <Icon icon="mdi:eye" width="24" height="24" />
+</Story>
+
+<Story name="Disabled" args={{ disabled: true }}>
+  <Icon icon="mdi:eye" width="24" height="24" />
+</Story>

package/src/lib/stories/developer tools/directives/clickOutside/index.mdx

@@ -0,0 +1,25 @@
+import { Source } from '@storybook/blocks';
+
+# Click Outside
+
+Event that fires after clicking outside the target component
+
+<Source
+  dark
+  language="js"
+  code={`
+import { clickOutside } '@flightlesslabs/dodo-ui';
+`}
+/>
+
+Attach it to a component
+
+<Source
+  dark
+  language="js"
+  code={`
+<div
+  use:clickOutside={onClickOutside}
+  ...
+`}
+/>

package/src/lib/stories/developer tools/helpers/Numbers/cleanNumericString/cleanNumericString.ts

@@ -0,0 +1,27 @@
+/**
+ * Cleans the input string by removing all characters except numeric digits (0-9) and a single decimal point.
+ * Only the first decimal point is retained; all subsequent dots are removed.
+ *
+ * @param {string} input - The input string to be cleaned.
+ * @returns {string} - A string containing only digits and at most one decimal point.
+ *
+ * @example
+ * cleanNumericString("abc123.45.67def"); // returns "123.4567"
+ * cleanNumericString("a1b2c3");          // returns "123"
+ * cleanNumericString("...12.3.4..5");    // returns "12.345"
+ */
+export default function cleanNumericString(input: string): string {
+  // Remove all characters except digits and dots
+  const filtered = input.replace(/[^0-9.]/g, '');
+
+  // Split by dot to separate parts
+  const parts = filtered.split('.');
+
+  if (parts.length === 1) {
+    // No dot present, just digits
+    return parts[0];
+  } else {
+    // Keep only first dot, join the rest parts without dots
+    return parts[0] + '.' + parts.slice(1).join('');
+  }
+}

package/src/lib/stories/developer tools/helpers/Numbers/cleanNumericString/index.mdx

@@ -0,0 +1,20 @@
+import { Source } from '@storybook/blocks';
+
+# cleanNumericString
+
+Cleans the input string by removing all characters except numeric digits (0-9) and a single decimal point.
+Only the first decimal point is retained; all subsequent dots are removed.
+
+---
+
+## Basic Usage
+
+<Source
+  dark
+  language="ts"
+  code={`
+import { cleanNumericString } from '@flightlesslabs/dodo-ui';
+
+const result = cleanNumericString("abc123.45.67def"); // result === "123.4567"
+`}
+/>

package/src/lib/stories/developer tools/helpers/Numbers/isValidNumberValue/index.mdx

@@ -0,0 +1,71 @@
+import { Source } from '@storybook/blocks';
+
+# isValidNumberValue
+
+Utility function to validate whether a string is a valid number based on customizable settings including minimum, maximum, decimal places, and allowance of negative numbers.
+
+---
+
+## Basic Usage
+
+Validates a string as a number with default settings (no decimals allowed, no negatives allowed, strict checking):
+
+<Source
+  dark
+  language="ts"
+  code={`
+import { isValidNumberValue } from '@flightlesslabs/dodo-ui';
+
+const result = isValidNumberValue("123");
+console.log(result); // true
+`}
+/>
+
+---
+
+## With Settings
+
+Customize validation rules:
+
+- `min` — minimum allowed value (inclusive)
+- `max` — maximum allowed value (inclusive)
+- `allowNegativeValues` — whether negatives are allowed
+- `decimalPlaces` — max decimal places allowed
+- `log` — enable detailed logging
+- `strict` — Strict checking, Full text - keep it enabled, Partial text - keep it disabled
+
+<Source
+  dark
+  language="ts"
+  code={`
+import { isValidNumberValue } from '@flightlesslabs/dodo-ui';
+
+const result1 = isValidNumberValue("123.456", { decimalPlaces: 3, log: true });
+const result2 = isValidNumberValue("-50", { allowNegativeValues: true, min: -100 });
+const result3 = isValidNumberValue("200", { max: 150 });
+
+const result4 = isValidNumberValue("-", { allowNegativeValues: true });
+const result5 = isValidNumberValue("-", { allowNegativeValues: true, strict: false });
+
+console.log(result1); // true
+console.log(result2); // true
+console.log(result3); // false (exceeds max)
+console.log(result4); // false (fails in strict check)
+console.log(result5); // true (pass in strict check)
+`}
+/>
+
+---
+
+## Type Definition
+
+```ts
+export type IsValidNumberValueSettings = {
+  min?: number;
+  max?: number;
+  allowNegativeValues?: boolean;
+  decimalPlaces?: number;
+  log?: boolean;
+  strict?: boolean;
+};
+```

package/src/lib/stories/developer tools/helpers/Numbers/isValidNumberValue/isValidNumberValue.ts

@@ -0,0 +1,156 @@
+import createLogger from '../../logger/logger.js';
+
+export type IsValidNumberValueSettings = {
+  /**
+   * Minimum allowed numeric value (inclusive).
+   */
+  min?: number;
+
+  /**
+   * Maximum allowed numeric value (inclusive).
+   */
+  max?: number;
+
+  /**
+   * Whether negative numbers are allowed.
+   * Defaults to false.
+   */
+  allowNegativeValues?: boolean;
+
+  /**
+   * Maximum allowed decimal places.
+   * Defaults to 0 (no decimals allowed).
+   */
+  decimalPlaces?: number;
+
+  /**
+   * Whether to enable logging.
+   * Defaults to false.
+   */
+  log?: boolean;
+
+  /**
+   * Strict checking, Full text - keep it enabled, Partial text - keep it disabled
+   * Defaults to true.
+   */
+  strict?: boolean;
+};
+
+/**
+ * Checks if the input string is a valid numeric string.
+ * Allows integers, decimals, negative numbers, and scientific notation.
+ *
+ * @param str - Input string to validate.
+ * @returns True if string is numeric, false otherwise.
+ */
+function isNumericString(str: string): boolean {
+  if (typeof str !== 'string') return false;
+  const trimmed = str.trim();
+  if (trimmed === '') return false;
+  const num = Number(trimmed);
+  return !isNaN(num) && isFinite(num);
+}
+
+/**
+ * Validates whether a string represents a valid number based on provided settings.
+ *
+ * @param value - The string to validate as a number.
+ * @param settings - Optional validation settings.
+ * @param settings.min - Minimum allowed value (inclusive).
+ * @param settings.max - Maximum allowed value (inclusive).
+ * @param settings.allowNegativeValues - Whether negative numbers are allowed.
+ * @param settings.decimalPlaces - Maximum allowed decimal places.
+ * @param settings.log - Whether to enable detailed logging.
+ * @param settings.strict - Whether to enable Strict checking, Full text - keep it enabled, Partial text - keep it disabled
+ *
+ * @returns True if the value is a valid number according to the settings; otherwise false.
+ *
+ * @example
+ * ```ts
+ * isValidNumberValue("123.45", { decimalPlaces: 2, log: true });
+ * isValidNumberValue("-50", { allowNegativeValues: true, min: -100 });
+ * ```
+ */
+export default function isValidNumberValue(
+  value: string,
+  settings?: IsValidNumberValueSettings,
+): boolean {
+  const allowNegativeValues = settings?.allowNegativeValues || false;
+  const decimalPlaces = settings?.decimalPlaces || 0;
+  const valueFormatted = value.trim();
+  const log = settings?.log || false;
+  const logger = createLogger({
+    label: 'isValidNumberValue',
+    show: log,
+  });
+  const min = settings?.min;
+  const max = settings?.max;
+  const strict = settings?.strict === false ? false : true;
+
+  logger.info(`Validating value: "${valueFormatted}"`);
+
+  if (strict && !isNumericString(valueFormatted)) {
+    logger.warn('Invalid input: strict checking is enaabled and the text failed the checks');
+    return false;
+  }
+
+  if (valueFormatted === '') {
+    logger.info('Valid input: Blank value');
+    return true;
+  }
+
+  if (allowNegativeValues && valueFormatted === '-') {
+    logger.info(`Valid input: Single '-' sign allowed as a negative placeholder.`);
+    return true;
+  }
+
+  if (!decimalPlaces && valueFormatted.includes('.')) {
+    logger.warn('Invalid input: Decimals not allowed');
+    return false;
+  }
+
+  const dotCount = (valueFormatted.match(/\./g) || []).length;
+
+  if (dotCount > 1) {
+    logger.warn('Invalid input: More than one decimal point detected.');
+    return false;
+  }
+
+  const parts = valueFormatted.split('.');
+
+  if (parts[1]?.length > decimalPlaces) {
+    logger.warn(
+      `Invalid input: Number has ${parts[1].length} decimal places, exceeding the allowed limit of ${decimalPlaces}.`,
+    );
+    return false;
+  }
+
+  if (!isNumericString(valueFormatted)) {
+    logger.warn('Invalid input: String is not a valid number.');
+    return false;
+  }
+
+  const numericValue = Number(valueFormatted);
+
+  if (!allowNegativeValues && numericValue < 0) {
+    logger.warn('Invalid input: Negative numbers are not allowed.');
+    return false;
+  }
+
+  if (min !== undefined && numericValue < min) {
+    logger.warn(
+      `Invalid input: Number ${numericValue} is less than the minimum allowed value of ${min}.`,
+    );
+    return false;
+  }
+
+  if (max !== undefined && numericValue > max) {
+    logger.warn(
+      `Invalid input: Number ${numericValue} exceeds the maximum allowed value of ${max}.`,
+    );
+    return false;
+  }
+
+  logger.info('Validation passed: Input is a valid number according to the provided settings.');
+  return true;
+}

package/src/lib/stories/developer tools/helpers/logger/index.mdx

@@ -0,0 +1,63 @@
+import { Source } from '@storybook/blocks';
+
+# Logger Utility
+
+A customizable logger function that supports:
+
+- Log levels (`info`, `warn`, `error`)
+- Optional labels
+- A `show` flag to toggle logging
+- Console output with timestamps
+
+## Import
+
+Import the logger creation function:
+
+<Source dark language="ts" code={`import { createLogger } from '@flightlesslabs/dodo-ui';`} />
+
+## Basic Usage
+
+Create a logger and log different types of messages:
+
+<Source
+  dark
+  language="ts"
+  code={`const logger = createLogger({
+  label: 'AuthService',
+});
+
+logger.info('User logged in');
+logger.warn('Token is about to expire');
+logger.error('Login failed', new Error('Invalid credentials'));
+`}
+/>
+
+## Disable Logging
+
+You can use the \`show\` flag to completely silence the logger (e.g., in production):
+
+<Source
+  dark
+  language="ts"
+  code={`const logger = createLogger({
+  show: false,
+});
+
+logger.info('This will not be logged');
+`}
+/>
+
+## Level Filtering
+
+The logger will only show messages **at or above** the configured `level`:
+
+<Source
+  dark
+  language="ts"
+  code={`const logger = createLogger();
+
+logger.info('This will NOT show');
+logger.warn('This WILL show');
+logger.error('This WILL show');
+`}
+/>

package/src/lib/stories/developer tools/helpers/logger/logger.ts

@@ -0,0 +1,46 @@
+export type LogLevel = 'info' | 'warn' | 'error';
+
+export interface LoggerOptions {
+  /**
+   * Optional label to prefix log entries.
+   */
+  label?: string;
+
+  /**
+   * Whether to actually show logs.
+   * Defaults to true.
+   */
+  show?: boolean;
+}
+
+/**
+ * Formats the log message with timestamp, label, and level.
+ */
+export function formatPrefix(level: LogLevel, label?: string): string {
+  const timestamp = new Date().toISOString();
+  const labelPart = label ? `[${label}]` : '';
+  return `[${timestamp}] ${labelPart} [${level.toUpperCase()}]`;
+}
+
+/**
+ * Creates a logger that logs every call unless disabled by show=false.
+ */
+export default function createLogger(options: LoggerOptions = {}) {
+  const { label, show = true } = options;
+
+  function shouldLog() {
+    return show;
+  }
+
+  return {
+    info: (msg: unknown, ...optionalParams: unknown[]) => {
+      if (shouldLog()) console.info(formatPrefix('info', label), msg, ...optionalParams);
+    },
+    warn: (msg: unknown, ...optionalParams: unknown[]) => {
+      if (shouldLog()) console.warn(formatPrefix('warn', label), msg, ...optionalParams);
+    },
+    error: (msg: unknown, ...optionalParams: unknown[]) => {
+      if (shouldLog()) console.error(formatPrefix('error', label), msg, ...optionalParams);
+    },
+  };
+}

package/src/lib/stories/developer tools/philosophy/Colors/Colors.mdx

@@ -0,0 +1,43 @@
+import { Meta, Story, Source } from '@storybook/blocks';
+import * as ColorsStories from './Colors.stories.svelte';
+import * as OpacityStories from './Opacity.stories.svelte';
+
+<Meta of={ColorsStories} />
+
+# Colors
+
+We are using an extensive color pallet identical to [Tailwind Css](https://tailwindcss.com/docs/colors) Colors. The colors are adjusted for dark and light themes.
+
+## Main Colors
+
+<Story of={ColorsStories.Main} />
+
+Greyscale colors
+
+<Story of={ColorsStories.ColorsNeutral} />
+
+Constant Colors
+
+<Story of={ColorsStories.ColorsConstant} />
+
+## Base Color
+
+<Story of={ColorsStories.ColorsBase} />
+
+Greyscale colors
+
+<Story of={ColorsStories.BaseColorsNeutral} />
+
+## Adjusting opacity
+
+Opacity can be adjusted using css `color-mix` function.
+
+<Source
+  dark
+  language="css"
+  code={`
+color-mix(in oklab, var(--dodo-color-primary-800) 10%, transparent)
+`}
+/>
+
+<Story of={OpacityStories.Main} meta={OpacityStories} />

package/src/lib/stories/developer tools/philosophy/Colors/Colors.stories.svelte

@@ -0,0 +1,22 @@
+<script module lang="ts">
+  import { defineMeta } from '@storybook/addon-svelte-csf';
+  import Colors from './Colors.svelte';
+
+  // More on how to set up stories at: https://storybook.js.org/docs/writing-stories
+  const { Story } = defineMeta({
+    component: Colors,
+    args: {
+      swatchType: 'colors',
+    },
+  });
+</script>
+
+<Story name="Main" />
+
+<Story name="ColorsNeutral" args={{ swatchType: 'colors-neutral' }} />
+
+<Story name="ColorsConstant" args={{ swatchType: 'colors-constant' }} />
+
+<Story name="ColorsBase" args={{ swatchType: 'base-colors' }} />
+
+<Story name="BaseColorsNeutral" args={{ swatchType: 'base-colors-neutral' }} />

package/src/lib/stories/developer tools/philosophy/Colors/Opacity.stories.svelte

@@ -0,0 +1,11 @@
+<script module lang="ts">
+  import { defineMeta } from '@storybook/addon-svelte-csf';
+  import Opacity from './Opacity.svelte';
+
+  // More on how to set up stories at: https://storybook.js.org/docs/writing-stories
+  const { Story } = defineMeta({
+    component: Opacity,
+  });
+</script>
+
+<Story name="Main" />

package/src/lib/stories/developer tools/philosophy/Themes.mdx

@@ -0,0 +1,23 @@
+import { Source } from '@storybook/blocks';
+import darkThemeToggleImage from '$lib/stories/assets/dark-theme-toggle.png';
+
+# Themes
+
+## Dark theme
+
+dark theme can be activated by adding `.dodo-theme--dark` class on the top container.
+
+<Source
+  dark
+  language="html"
+  code={`
+ <body class="dodo-theme--dark">
+ ...
+`}
+/>
+
+## Toggle theme in documentation
+
+Use the moon icon to toogle theme in documentation mode
+
+<img src={darkThemeToggleImage} />