@flightlesslabs/dodo-ui 0.19.1 → 0.20.0

package/src/lib/utils/time/date-creator/createDate/createDate.mdx

@@ -0,0 +1,123 @@
+import { Source } from '@storybook/addon-docs/blocks';
+
+# createDate
+
+A centralized date factory built on top of `dayjs`.
+
+This utility ensures **consistent parsing, timezone handling, and validation** across your application.
+
+## 📦 Import
+
+<Source
+  dark
+  language="ts"
+  code={`
+import { createDate } from '@flightlesslabs/dodo-ui';
+`}
+/>
+
+## 🚀 Basic Usage
+
+### Current Date
+
+<Source
+  dark
+  language="ts"
+  code={`
+const now = createDate();
+console.log(now.format());
+`}
+/>
+
+### Parse a Date
+
+<Source
+  dark
+  language="ts"
+  code={`
+const date = createDate("01-02-2025", "DD-MM-YYYY");
+console.log(date.format());
+`}
+/>
+
+## 🌍 Timezone & UTC
+
+### UTC Mode
+
+<Source
+  dark
+  language="ts"
+  code={`
+const utcDate = createDate("2025-01-01T12:00:00Z", undefined, {
+  utc: true,
+});
+`}
+/>
+
+### Timezone Conversion
+
+<Source
+  dark
+  language="ts"
+  code={`
+const indiaTime = createDate("01-01-2025", "DD-MM-YYYY", {
+  timezone: "Asia/Kolkata",
+});
+`}
+/>
+
+## ⚙️ Options
+
+<Source
+  dark
+  language="ts"
+  code={`
+interface CreateDateOptions {
+  timezone?: string;
+  utc?: boolean;
+  strict?: boolean;
+  throwOnInvalid?: boolean;
+}
+`}
+/>
+
+## 🔁 Behavior Priority
+
+1. utc (highest priority)
+2. timezone
+3. local
+
+---
+
+### timezone
+
+- IANA timezone string
+- Interprets input in given timezone
+
+---
+
+### utc
+
+- Forces UTC mode
+
+---
+
+### strict
+
+- Only applies when format is provided
+- Has no effect on ISO / timestamps
+
+---
+
+### throwOnInvalid
+
+- Throws error if date is invalid
+
+---
+
+## 📥 Supported Inputs
+
+- string
+- number (timestamp)
+- Date object
+- undefined

package/src/lib/utils/time/date-creator/createDate/createDate.ts

@@ -0,0 +1,6 @@
+import { createDateFactory } from '../createDateFactory/createDateFactory.js';
+import defaultDayjs from '../createDateFactory/dayjs.js';
+
+const { createDate } = createDateFactory(defaultDayjs);
+
+export { createDate };

package/src/lib/utils/time/date-creator/createDateFactory/createDateFactory.mdx

@@ -0,0 +1,127 @@
+import { Source } from '@storybook/addon-docs/blocks';
+
+# createDateFactory
+
+A **factory function** that creates a `createDate` utility with an optional custom `dayjs` instance.
+
+This allows advanced users to:
+
+- Inject their own configured `dayjs`
+- Share plugins across multiple libraries
+- Avoid global `dayjs.extend` pollution
+- Create isolated date environments
+
+---
+
+## 📦 Import
+
+<Source
+  dark
+  language="ts"
+  code={`
+import { createDateFactory } from '@flightlesslabs/dodo-ui';
+`}
+/>
+
+---
+
+## 🚀 Basic Usage
+
+### Default Factory
+
+<Source
+  dark
+  language="ts"
+  code={`
+import { createDateFactory } from '@flightlesslabs/dodo-ui';
+
+const { createDate } = createDateFactory();
+
+const now = createDate();
+console.log(now.format());
+`}
+/>
+
+---
+
+## 🧠 Why Use a Factory?
+
+Instead of relying on global `dayjs.extend`, you can:
+
+- isolate plugin setups
+- avoid conflicts in monorepos
+- support multiple configurations
+- improve testability
+
+---
+
+## 🔌 Custom Dayjs Instance
+
+### Inject your own configured instance
+
+<Source
+  dark
+  language="ts"
+  code={`
+import dayjs from 'dayjs';
+import utc from 'dayjs/plugin/utc';
+import timezone from 'dayjs/plugin/timezone';
+
+dayjs.extend(utc);
+dayjs.extend(timezone);
+
+const { createDate } = createDateFactory(dayjs);
+
+const date = createDate("2025-01-01", "YYYY-MM-DD");
+`}
+/>
+
+---
+
+## ⚙️ Behavior
+
+The factory wraps your `dayjs` instance and preserves:
+
+- UTC handling
+- Timezone support
+- Strict parsing
+- Validation options
+
+---
+
+## 🔁 Priority Order
+
+1. utc (highest priority)
+2. timezone
+3. local parsing
+
+---
+
+## 📥 Returned API
+
+<Source
+  dark
+  language="ts"
+  code={`
+{
+  createDate: Function,
+  dayjs: DayjsInstance
+}
+`}
+/>
+
+---
+
+## 🧪 Example: Multiple Factories
+
+<Source
+  dark
+  language="ts"
+  code={`
+const factoryA = createDateFactory(dayjsA);
+const factoryB = createDateFactory(dayjsB);
+
+factoryA.createDate("2025-01-01");
+factoryB.createDate("2025-01-01");
+`}
+/>

package/src/lib/utils/time/date-creator/createDateFactory/createDateFactory.ts

@@ -0,0 +1,54 @@
+import defaultDayjs from './dayjs.js';
+import type { CreateDateInput, CreateDateFormat, CreateDateOptions } from './types.js';
+
+type Dayjs = typeof defaultDayjs;
+
+export function createDateFactory(customDayjs?: Dayjs) {
+  const d = customDayjs ?? defaultDayjs;
+
+  function createDate(): ReturnType<Dayjs>;
+  function createDate(
+    date: CreateDateInput,
+    format?: CreateDateFormat,
+    options?: CreateDateOptions,
+  ): ReturnType<Dayjs>;
+
+  function createDate(
+    date?: CreateDateInput,
+    format?: CreateDateFormat,
+    options: CreateDateOptions = {},
+  ) {
+    const { timezone, utc, strict = false, throwOnInvalid = false } = options;
+
+    const input = date ?? undefined;
+
+    let instance: ReturnType<Dayjs>;
+
+    // 1. UTC takes highest priority
+    if (utc) {
+      instance = format ? d.utc(input, format, strict) : d.utc(input);
+    }
+
+    // 2. Timezone
+    else if (timezone) {
+      instance = format ? d.tz(input, format, timezone) : d.tz(input, timezone);
+    }
+
+    // 3. Local
+    else {
+      instance = format ? d(input, format, strict) : d(input);
+    }
+
+    // 4. Validation
+    if (throwOnInvalid && !instance.isValid()) {
+      throw new Error('Invalid date input');
+    }
+
+    return instance;
+  }
+
+  return {
+    createDate,
+    dayjs: d,
+  };
+}

package/src/lib/utils/time/date-creator/createDateFactory/dayjs.ts

@@ -0,0 +1,15 @@
+import dayjsFactory from 'dayjs';
+import utcPlugin from 'dayjs/plugin/utc.js';
+import timezonePlugin from 'dayjs/plugin/timezone.js';
+import customParseFormatPlugin from 'dayjs/plugin/customParseFormat.js';
+import isBetweenPlugin from 'dayjs/plugin/isBetween.js';
+
+const dayjs = dayjsFactory as typeof dayjsFactory;
+
+// default plugin setup
+dayjs.extend(utcPlugin);
+dayjs.extend(timezonePlugin);
+dayjs.extend(customParseFormatPlugin);
+dayjs.extend(isBetweenPlugin);
+
+export default dayjs;

package/src/lib/utils/time/date-creator/createDateFactory/types.ts

@@ -0,0 +1,11 @@
+import type { ConfigType } from 'dayjs';
+
+export type CreateDateInput = ConfigType;
+export type CreateDateFormat = string | undefined;
+
+export interface CreateDateOptions {
+  timezone?: string;
+  utc?: boolean;
+  strict?: boolean;
+  throwOnInvalid?: boolean;
+}

package/src/lib/utils/time/timeout/timeout.mdx

@@ -0,0 +1,134 @@
+import { Source } from '@storybook/addon-docs/blocks';
+
+# timeout
+
+A simple utility to delay execution using Promises.
+
+Useful for **pausing async workflows**, **simulating delays**, or **controlling execution timing**.
+
+---
+
+## 📦 Import
+
+<Source
+  dark
+  language="ts"
+  code={`
+import { timeout } from '@flightlesslabs/dodo-ui';
+`}
+/>
+
+---
+
+## 🚀 Basic Usage
+
+<Source
+  dark
+  language="ts"
+  code={`
+await timeout(1000); // waits 1 second
+`}
+/>
+
+---
+
+## 🎯 Resolve with Value
+
+You can optionally pass a value that will be returned after the delay.
+
+<Source
+  dark
+  language="ts"
+  code={`
+const result = await timeout(500, "done");
+
+console.log(result); // "done"
+`}
+/>
+
+---
+
+## ⚙️ API
+
+<Source
+  dark
+  language="ts"
+  code={`
+function timeout<T = void>(
+  milliseconds: number,
+  value?: T
+): Promise<T>
+`}
+/>
+
+---
+
+### `milliseconds`
+
+- Time to wait before resolving (in ms)
+- Must be `>= 0`
+
+---
+
+### `value`
+
+- Optional value to resolve with
+- Defaults to `undefined`
+
+---
+
+## ⚠️ Error Handling
+
+If a negative duration is provided, the promise will reject:
+
+<Source
+  dark
+  language="ts"
+  code={`
+await timeout(-1); // ❌ throws Error
+`}
+/>
+
+---
+
+## 🧠 Use Cases
+
+- Delay execution in async functions
+- Simulate API latency in tests
+- Simple throttling or pacing logic
+
+---
+
+## 🔍 Examples
+
+### Async Flow
+
+<Source
+  dark
+  language="ts"
+  code={`
+async function run() {
+  console.log("Start");
+
+await timeout(1000);
+
+console.log("End");
+}
+`}
+/>
+
+---
+
+### With Data
+
+<Source
+  dark
+  language="ts"
+  code={`
+const data = await timeout(300, { success: true });
+
+console.log(data.success); // true
+`}
+/>
+
+---

package/src/lib/utils/time/timeout/timeout.ts

@@ -0,0 +1,29 @@
+/**
+ * Creates a promise that resolves after a specified delay.
+ *
+ * Useful for pausing execution in async workflows,
+ * throttling operations, or simulating delays in tests.
+ *
+ * @group Time
+ *
+ * @param milliseconds - Time to wait in milliseconds.
+ * @param value - Optional value to resolve with.
+ *
+ * @returns A promise that resolves after the delay.
+ *
+ * @example
+ * await timeout(1000);
+ *
+ * @example
+ * const result = await timeout(1000, "done");
+ * console.log(result); // "done"
+ */
+export function timeout<T = void>(milliseconds: number, value?: T): Promise<T> {
+  if (milliseconds < 0) {
+    return Promise.reject(new Error('Timeout duration must be >= 0'));
+  }
+
+  return new Promise<T>((resolve) => {
+    setTimeout(() => resolve(value as T), milliseconds);
+  });
+}

package/dist/stories/Home.mdx

@@ -1,72 +0,0 @@
-import { Source } from '@storybook/addon-docs/blocks';
-import item from '../../../package.json?raw';
-
-<main style={{ textAlign: 'center' }}>
-
-<img src="dodo-circle-6.png" style={{ width: 200, height: 'auto' }} />
-
-# Dodo UI
-
-<h3 style={{ fontWeight: 500 }}>v{JSON.parse(item)?.version}</h3>
-
-<h3 style={{ fontWeight: 400 }}>An open-source, opinionated UI framework for Svelte.</h3>
-
-### [Github](https://github.com/flightlesslabs/dodo-ui) - [npm](https://www.npmjs.com/package/@flightlesslabs/dodo-ui) - [Customize](?path=/docs/developer-tools-customize-autocustomize--docs)
-
-</main>
-
-<br />
-<br />
-
-## Install
-
-pnpm
-
-<Source
-  dark
-  language="bash"
-  code={`
-pnpm add @flightlesslabs/dodo-ui
-`}
-/>
-
-npm
-
-<Source
-  dark
-  language="bash"
-  code={`
-npm i @flightlesslabs/dodo-ui
-`}
-/>
-
-## Add css
-
-Add global css in your `+layout.svelte` file
-
-<Source
-  dark
-  language="js"
-  code={`
-import '@flightlesslabs/dodo-ui/styles/global.css';
-`}
-/>
-
-## Use it!
-
-Lets import [Button](?path=/docs/components-form-button--docs) component. Checkout documentation for [Button](?path=/docs/components-form-button--docs)
-
-<Source
-  dark
-  language="js"
-  code={`
-import { Button } '@flightlesslabs/dodo-ui';
-`}
-/>
-
-## Explore more
-
-- [Dark Theme](?path=/docs/developer-tools-philosophy-themes--docs#dark-theme)
-- [Colors](?path=/docs/developer-tools-philosophy-colors--docs)
-- [Customize](?path=/docs/developer-tools-customize-autocustomize--docs)
-- [Adjust Color Opacity](?path=/docs/developer-tools-philosophy-colors--docs#adjusting-opacity)

package/dist/stories/components/Form/Button/Button.stories.svelte

@@ -1,57 +0,0 @@
-<script module lang="ts">import { defineMeta } from '@storybook/addon-svelte-csf';
-import Button, { buttonTypeArray } from './Button.svelte';
-import { componentRoundnessArray } from '../../../../types/roundness.js';
-import { componentColorArray } from '../../../../types/colors.js';
-import { componentWeightArray } from '../../../../types/weight.js';
-import { componentSizeArray } from '../../../../types/size.js';
-export const storyButtonArgTypes = {
-    type: {
-        control: { type: 'select' },
-        options: buttonTypeArray,
-    },
-    color: {
-        control: { type: 'select' },
-        options: componentColorArray,
-    },
-    variant: {
-        control: { type: 'select' },
-        options: componentWeightArray,
-    },
-    roundness: {
-        control: { type: 'select' },
-        options: componentRoundnessArray,
-    },
-    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: Button,
-    tags: ['autodocs'],
-    argTypes: storyButtonArgTypes,
-});
-</script>
-
-<!-- Button with default style -->
-<Story name="Primary">Click me!</Story>
-
-<!-- Button with border around it -->
-<Story name="Outline" args={{ outline: true, variant: 'text' }}>Click me!</Story>
-
-<Story name="Disabled" args={{ disabled: true }}>Click me!</Story>
-
-<!-- Form submit button -->
-<Story name="Sumbit Button" args={{ type: 'submit' }}>Submit Form</Story>
-
-<!-- Form submit button -->
-<Story name="Full width Button" args={{ fullWidth: true }}>Click me!</Story>
-
-<!-- Anchor Link styled like a Button -->
-<Story
-  name="Link Button"
-  args={{ href: 'https://www.w3schools.com/tags/tag_a.asp', target: '_blank' }}
->
-  Link
-</Story>