maz-ui 5.0.0 → 5.1.0-beta.0

package/docs/ecosystem/utils/throttle.md

@@ -0,0 +1,63 @@
+---
+title: "throttle"
+description: "Wrap a function so it runs immediately, then at most once every N milliseconds - perfect for scroll, mousemove and resize handlers."
+package: "@maz-ui/utils"
+url: "https://maz-ui.com/ecosystem/utils/throttle"
+---
+
+# throttle
+
+> Wrap a function so it runs immediately, then at most once every N milliseconds - perfect for scroll, mousemove and resize handlers.
+
+- Package: `@maz-ui/utils`
+- Import: `import { throttle } from '@maz-ui/utils/helpers/throttle'`
+- Web: https://maz-ui.com/ecosystem/utils/throttle
+
+Unlike [`debounce`](./debounce.md) - which waits for a quiet period - `throttle` lets the first call through and rate-limits the rest.
+
+## Usage
+
+```ts
+import { throttle } from '@maz-ui/utils'
+
+const onScroll = throttle(() => {
+  console.log('scroll position', window.scrollY)
+}, 200)
+
+window.addEventListener('scroll', onScroll)
+```
+
+## API
+
+```ts
+function throttle<T extends (...args: any[]) => any>(
+  func: T,
+  limit: number,
+): (...args: Parameters<T>) => void
+```
+
+| Parameter | Type       | Description                                |
+| --------- | ---------- | ------------------------------------------ |
+| `func`    | `Function` | The function to throttle                   |
+| `limit`   | `number`   | Minimum interval between executions, in ms |
+
+The first call always runs immediately. Subsequent calls within `limit` are coalesced - only the most recent set of arguments is replayed once the window elapses.
+
+## Examples
+
+Throttle a window resize handler:
+
+```ts
+import { throttle } from '@maz-ui/utils'
+
+const onResize = throttle(() => {
+  console.log('width:', window.innerWidth)
+}, 250)
+
+window.addEventListener('resize', onResize)
+```
+
+## Related
+
+- [`throttleId`](./throttle-id.md) - per-key throttle for async functions, returning a promise.
+- [`debounce`](./debounce.md) - fires only once activity stops.

package/docs/ecosystem/utils/truthy-filter.md

@@ -0,0 +1,37 @@
+---
+title: "truthyFilter"
+description: "Type guard that filters out falsy values (`false`, `''`, `0`, `null`, `undefined`) while narrowing the TypeScript type."
+package: "@maz-ui/utils"
+url: "https://maz-ui.com/ecosystem/utils/truthy-filter"
+---
+
+# truthyFilter
+
+> Type guard that filters out falsy values (`false`, `''`, `0`, `null`, `undefined`) while narrowing the TypeScript type.
+
+- Package: `@maz-ui/utils`
+- Import: `import { truthyFilter } from '@maz-ui/utils/helpers/truthyFilter'`
+- Web: https://maz-ui.com/ecosystem/utils/truthy-filter
+
+Pass it directly to `Array.prototype.filter` to drop nullish/empty entries while telling TypeScript the result no longer contains those types.
+
+## Usage
+
+```ts
+import { truthyFilter } from '@maz-ui/utils'
+
+const items: (string | null | undefined)[] = ['a', null, 'b', undefined, '']
+const cleaned = items.filter(truthyFilter)
+// cleaned has type string[]
+// cleaned = ['a', 'b']
+```
+
+## API
+
+```ts
+type Truthy<T> = T extends false | '' | 0 | null | undefined ? never : T
+
+function truthyFilter<T>(value: T): value is Truthy<T>
+```
+
+The function returns `Boolean(value)` - its real value is in the type predicate, which narrows away the falsy variants for downstream type-checking.

package/docs/ecosystem/utils/types/deep-key-of.md

@@ -0,0 +1,54 @@
+---
+title: "DeepKeyOf"
+description: "Recursively build a union of dot-separated key paths for any nested object type."
+package: "@maz-ui/utils"
+url: "https://maz-ui.com/ecosystem/utils/types/deep-key-of"
+---
+
+# DeepKeyOf
+
+> Recursively build a union of dot-separated key paths for any nested object type.
+
+- Package: `@maz-ui/utils`
+- Import: `import type { DeepKeyOf } from '@maz-ui/utils/ts-helpers/DeepKeyOf'`
+- Web: https://maz-ui.com/ecosystem/utils/types/deep-key-of
+
+Use it to type i18n keys, nested form paths, or any string that must reference a leaf of a known object shape.
+
+## Usage
+
+```ts
+import type { DeepKeyOf } from '@maz-ui/utils'
+
+interface Config {
+  app: {
+    name: string
+    theme: {
+      mode: 'light' | 'dark'
+      primary: string
+    }
+  }
+  version: number
+}
+
+type Keys = DeepKeyOf<Config>
+// → 'app.name' | 'app.theme.mode' | 'app.theme.primary' | 'version'
+```
+
+## API
+
+```ts
+type DeepKeyOf<T> = T extends object
+  ? { [K in keyof T]: K extends string
+      ? T[K] extends object
+        ? `${K}.${DeepKeyOf<T[K]>}`
+        : K
+      : never
+    }[keyof T]
+  : never
+```
+
+## Notes
+
+- Numeric and symbol keys are excluded - only `string`-keyed properties are walked.
+- Array types are objects, so `DeepKeyOf<{ items: string[] }>` produces `'items.0' | 'items.1' | …` only if the array has tuple typing. With a regular `string[]`, the recursion terminates at `'items'`.

package/docs/ecosystem/utils/types/deep-partial.md

@@ -0,0 +1,48 @@
+---
+title: "DeepPartial"
+description: "Recursive variant of TypeScript's `Partial<T>` - every property at every depth becomes optional."
+package: "@maz-ui/utils"
+url: "https://maz-ui.com/ecosystem/utils/types/deep-partial"
+---
+
+# DeepPartial
+
+> Recursive variant of TypeScript's `Partial<T>` - every property at every depth becomes optional.
+
+- Package: `@maz-ui/utils`
+- Import: `import type { DeepPartial } from '@maz-ui/utils/ts-helpers/DeepPartial'`
+- Web: https://maz-ui.com/ecosystem/utils/types/deep-partial
+
+## Usage
+
+```ts
+import type { DeepPartial } from '@maz-ui/utils'
+
+interface UserSettings {
+  notifications: {
+    email: boolean
+    push: boolean
+  }
+  theme: {
+    primary: string
+    secondary: string
+  }
+}
+
+const update: DeepPartial<UserSettings> = {
+  notifications: { email: false },
+}
+```
+
+## API
+
+```ts
+type DeepPartial<T> = T extends object
+  ? { [P in keyof T]?: DeepPartial<T[P]> }
+  : T
+```
+
+## Notes
+
+- Primitives (`string`, `number`, `boolean`, `null`, `undefined`, …) are returned unchanged.
+- Useful for partial-update payloads (`PATCH` requests, merge functions, default-options patterns).

package/docs/ecosystem/utils/types/deep-required.md

@@ -0,0 +1,45 @@
+---
+title: "DeepRequired"
+description: "Recursive variant of TypeScript's `Required<T>` - strips `?` from every property at every depth."
+package: "@maz-ui/utils"
+url: "https://maz-ui.com/ecosystem/utils/types/deep-required"
+---
+
+# DeepRequired
+
+> Recursive variant of TypeScript's `Required<T>` - strips `?` from every property at every depth.
+
+- Package: `@maz-ui/utils`
+- Import: `import type { DeepRequired } from '@maz-ui/utils/ts-helpers/DeepRequired'`
+- Web: https://maz-ui.com/ecosystem/utils/types/deep-required
+
+The mirror image of [`DeepPartial`](./deep-partial.md). Useful when you want a fully-resolved internal type derived from a public options interface.
+
+## Usage
+
+```ts
+import type { DeepRequired } from '@maz-ui/utils'
+
+interface Options {
+  cache?: {
+    ttl?: number
+    strategy?: 'memory' | 'disk'
+  }
+}
+
+type ResolvedOptions = DeepRequired<Options>
+// {
+//   cache: {
+//     ttl: number
+//     strategy: 'memory' | 'disk'
+//   }
+// }
+```
+
+## API
+
+```ts
+type DeepRequired<T> = Required<{
+  [K in keyof T]: T[K] extends Required<T[K]> ? T[K] : DeepRequired<T[K]>
+}>
+```

package/docs/ecosystem/utils/types/flatten-object-keys.md

@@ -0,0 +1,50 @@
+---
+title: "FlattenObjectKeys"
+description: "Build a union of dot-separated leaf paths for a nested object, with an optional prefix."
+package: "@maz-ui/utils"
+url: "https://maz-ui.com/ecosystem/utils/types/flatten-object-keys"
+---
+
+# FlattenObjectKeys
+
+> Build a union of dot-separated leaf paths for a nested object, with an optional prefix.
+
+- Package: `@maz-ui/utils`
+- Import: `import type { FlattenObjectKeys } from '@maz-ui/utils/ts-helpers/FlattenObjectKeys'`
+- Web: https://maz-ui.com/ecosystem/utils/types/flatten-object-keys
+
+Similar to [`DeepKeyOf`](./deep-key-of.md) but only yields **leaf** paths (skips intermediate object keys), and accepts a `Prefix` parameter for namespacing.
+
+## Usage
+
+```ts
+import type { FlattenObjectKeys } from '@maz-ui/utils'
+
+interface Config {
+  app: {
+    name: string
+    version: number
+  }
+  debug: boolean
+}
+
+type Leaves = FlattenObjectKeys<Config>
+// → 'app.name' | 'app.version' | 'debug'
+
+type Namespaced = FlattenObjectKeys<Config, 'config.'>
+// → 'config.app.name' | 'config.app.version' | 'config.debug'
+```
+
+## API
+
+```ts
+type FlattenObjectKeys<T extends Record<string, any>, Prefix extends string = ''> = {
+  [K in keyof T]: T[K] extends Record<string, any>
+    ? FlattenObjectKeys<T[K], `${Prefix}${K extends string ? K : ''}.`>
+    : `${Prefix}${K extends string ? K : ''}`
+}[keyof T]
+```
+
+## Notes
+
+- Unlike `DeepKeyOf`, intermediate object keys (e.g. `'app'` in the example) are not included - only the paths that resolve to non-object leaves.

package/docs/ecosystem/utils/types/generic-instance-type.md

@@ -0,0 +1,48 @@
+---
+title: "GenericInstanceType"
+description: "Extract the public instance type from a generic Vue component - solves the limitation where `InstanceType<typeof Component>` returns `any` for generic SFCs."
+package: "@maz-ui/utils"
+url: "https://maz-ui.com/ecosystem/utils/types/generic-instance-type"
+---
+
+# GenericInstanceType
+
+> Extract the public instance type from a generic Vue component - solves the limitation where `InstanceType<typeof Component>` returns `any` for generic SFCs.
+
+- Package: `@maz-ui/utils`
+- Import: `import type { GenericInstanceType } from '@maz-ui/utils/ts-helpers/GenericInstanceType'`
+- Web: https://maz-ui.com/ecosystem/utils/types/generic-instance-type
+
+Vue's `InstanceType<typeof Component>` does not work on **generic** components (`<script setup lang="ts" generic="T">`). `GenericInstanceType` walks the type to recover the exposed methods/refs typing.
+
+See the underlying TypeScript / Vue Language Tools issue: [vuejs/language-tools#3206](https://github.com/vuejs/language-tools/issues/3206).
+
+## Usage
+
+```ts
+import type { GenericInstanceType } from '@maz-ui/utils'
+import { ref } from 'vue'
+import MyGenericList from './MyGenericList.vue'
+
+const listRef = ref<GenericInstanceType<typeof MyGenericList> | null>(null)
+
+// listRef.value.focus() is fully typed
+```
+
+## API
+
+```ts
+type GenericInstanceType<T> = T extends new (...args: any[]) => infer R
+  ? R
+  : T extends (...args: any[]) => infer R
+    ? R extends { __ctx?: infer K }
+      ? Exclude<K, void> extends { expose: (...args: infer Y) => void }
+        ? Y[0] & InstanceType<DefineComponent>
+        : any
+      : any
+    : any
+```
+
+## Notes
+
+- Use this only for generic components. For non-generic SFCs, plain `InstanceType<typeof Component>` already works and is clearer.

package/docs/ecosystem/utils/types/infer-maybe-ref.md

@@ -0,0 +1,41 @@
+---
+title: "InferMaybeRef"
+description: "Unwrap a Vue `Ref<U>` to its inner `U` - leaves non-ref types unchanged."
+package: "@maz-ui/utils"
+url: "https://maz-ui.com/ecosystem/utils/types/infer-maybe-ref"
+---
+
+# InferMaybeRef
+
+> Unwrap a Vue `Ref<U>` to its inner `U` - leaves non-ref types unchanged.
+
+- Package: `@maz-ui/utils`
+- Import: `import type { InferMaybeRef } from '@maz-ui/utils/ts-helpers/InferMaybeRef'`
+- Web: https://maz-ui.com/ecosystem/utils/types/infer-maybe-ref
+
+Useful when authoring composables that accept either a plain value or a `Ref`, and you want a unified type for the inner value.
+
+## Usage
+
+```ts
+import type { InferMaybeRef } from '@maz-ui/utils'
+import { ref } from 'vue'
+
+const a = ref(42)
+const b = 42
+
+type A = InferMaybeRef<typeof a> // number
+type B = InferMaybeRef<typeof b> // number
+```
+
+## API
+
+```ts
+import type { Ref } from 'vue'
+
+type InferMaybeRef<T> = T extends Ref<infer U> ? U : T
+```
+
+## Notes
+
+- Pairs well with Vue's built-in [`unref()`](https://vuejs.org/api/reactivity-utilities.html#unref), which provides the same behaviour at runtime.

package/docs/ecosystem/utils/upper-first.md

@@ -0,0 +1,38 @@
+---
+title: "upperFirst"
+description: "Uppercase the first character of a string and leave the rest unchanged."
+package: "@maz-ui/utils"
+url: "https://maz-ui.com/ecosystem/utils/upper-first"
+---
+
+# upperFirst
+
+> Uppercase the first character of a string and leave the rest unchanged.
+
+- Package: `@maz-ui/utils`
+- Import: `import { upperFirst } from '@maz-ui/utils/helpers/upperFirst'`
+- Web: https://maz-ui.com/ecosystem/utils/upper-first
+
+## Usage
+
+```ts
+import { upperFirst } from '@maz-ui/utils'
+
+upperFirst('hello') // → 'Hello'
+upperFirst('hELLO') // → 'HELLO'
+upperFirst('') // → ''
+```
+
+## API
+
+```ts
+function upperFirst(value: string): string
+```
+
+| Parameter | Type     | Description           |
+| --------- | -------- | --------------------- |
+| `value`   | `string` | The string to process |
+
+## Notes
+
+- Does **not** lowercase the remaining characters - use [`capitalize`](./capitalize.md) for the same behaviour when you control the input shape.

package/docs/ecosystem/utils/user-visibility.md

@@ -0,0 +1,75 @@
+---
+title: "UserVisibility"
+description: "Track whether the user is currently looking at the tab using the Page Visibility API, with an optional grace timeout before declaring them away."
+package: "@maz-ui/utils"
+url: "https://maz-ui.com/ecosystem/utils/user-visibility"
+---
+
+# UserVisibility
+
+> Track whether the user is currently looking at the tab using the Page Visibility API, with an optional grace timeout before declaring them away.
+
+- Package: `@maz-ui/utils`
+- Import: `import { UserVisibility } from '@maz-ui/utils/helpers/userVisibility'`
+- Web: https://maz-ui.com/ecosystem/utils/user-visibility
+
+`UserVisibility` listens to `visibilitychange` events. When the tab becomes hidden, it waits `timeout` ms before invoking the callback with `isVisible: false` - this avoids spurious switches when the user briefly tabs away.
+
+## Usage
+
+```ts
+import { UserVisibility } from '@maz-ui/utils'
+
+const watcher = new UserVisibility(
+  ({ isVisible }) => {
+    if (isVisible) {
+      resumeVideo()
+    }
+    else {
+      pauseVideo()
+    }
+  },
+  { timeout: 3000 },
+)
+
+// later
+watcher.destroy()
+```
+
+## API
+
+```ts
+class UserVisibility {
+  constructor(callback: UserVisibilyCallback, options?: UserVisibilyOptions)
+
+  start(): void
+  destroy(): void
+}
+
+type UserVisibilyCallback = (payload: { isVisible: boolean }) => void
+```
+
+### Options
+
+| Option      | Type      | Default | Description                                                                       |
+| ----------- | --------- | ------- | --------------------------------------------------------------------------------- |
+| `timeout`   | `number`  | `5000`  | Grace period in ms before a hidden tab fires the `isVisible: false` callback.    |
+| `immediate` | `boolean` | `true`  | Fire the callback once on construction with the current visibility state.        |
+| `once`      | `boolean` | `false` | Auto-destroy after the first callback invocation.                                |
+
+## Examples
+
+Pause expensive timers when the user tabs away:
+
+```ts
+new UserVisibility(
+  ({ isVisible }) => {
+    isVisible ? animations.resume() : animations.pause()
+  },
+  { timeout: 0 }, // react immediately
+)
+```
+
+## Related
+
+- [`IdleTimeout`](./idle-timeout.md) - track in-page activity instead of tab visibility.