@rb-pulse/ui 1.2.24

package/index.ts

@@ -0,0 +1,281 @@
+/**
+ * @pulse/ui — Page, groupbox, and widget API for Pulse framework scripts.
+ *
+ * Use `definePage` to declare UI tabs and `groupbox` to arrange components
+ * into columns. Widget functions (`toggle`, `slider`, `button`, etc.) bind
+ * reactive signals from `@pulse/core` to UI controls.
+ *
+ * @example
+ * ```typescript
+ * import { defineComponent, signal, on } from '@pulse/core'
+ * import { definePage, groupbox, toggle, slider } from '@pulse/ui'
+ * import { KillAura } from '../player/KillAura'
+ * import { ReachHack } from '../player/ReachHack'
+ *
+ * // pages/1_Combat.ts
+ * export default definePage('Combat', { icon: 'swords' }, () => [
+ *   groupbox('left',  'Kill Aura', { icon: 'crosshair', mount: KillAura }),
+ *   groupbox('right', 'Reach',     { icon: 'ruler',     mount: ReachHack }),
+ * ])
+ * ```
+ */
+
+import type { ComponentDefinition, Signal, WidgetDef } from '@rb-pulse/core'
+
+// ── Page ───────────────────────────────────────────────────────────────────────
+
+/** Options for `definePage`. */
+export interface PageOpts {
+  /**
+   * Icon name shown in the tab bar.
+   * Required — build will error if missing.
+   * @example 'swords' | 'crosshair' | 'eye' | 'gear'
+   */
+  icon: string
+}
+
+/** Opaque page definition handle returned by `definePage`. */
+export interface PageDefinition {
+  readonly _name:    string
+  readonly _type:    'page'
+  readonly _groupboxes: GroupboxDef[]
+}
+
+/**
+ * Define a top-level tab in the script UI.
+ *
+ * Each exported `definePage` call maps to one tab in the Linoria / WindUI window.
+ * Pages are sorted by their filename prefix (e.g. `1_Combat.ts` before `2_Visuals.ts`).
+ * The factory is called once on initialisation.
+ *
+ * @param name    Display name shown in the tab bar (e.g. `'Combat'`)
+ * @param opts    `icon` is required; controls the tab icon
+ * @param factory Returns an array of groupbox definitions to lay out in the tab
+ *
+ * @example
+ * export default definePage('Combat', { icon: 'swords' }, () => [
+ *   groupbox('left',  'Kill Aura', { icon: 'crosshair', mount: KillAura }),
+ *   groupbox('right', 'Reach',     { icon: 'ruler',     mount: ReachHack }),
+ * ])
+ */
+export declare function definePage(
+  name:    string,
+  opts:    PageOpts,
+  factory: () => GroupboxDef[],
+): PageDefinition
+
+// ── Groupbox ───────────────────────────────────────────────────────────────────
+
+/** Options for `groupbox`. */
+export interface GroupboxOpts {
+  /**
+   * Icon name shown in the groupbox header.
+   * Required — build will error if missing.
+   */
+  icon: string
+  /**
+   * Mount a component's widgets directly into this groupbox.
+   * Equivalent to calling all the component's `return [...]` widgets inline.
+   */
+  mount?: ComponentDefinition<any>
+  /**
+   * Separator label rendered above this groupbox (decorative divider).
+   */
+  separator?: string
+  /**
+   * Exclude this groupbox from compat builds.
+   * Useful for features that only work on certain executors.
+   */
+  compatExclude?: boolean
+}
+
+/** Opaque groupbox definition handle. */
+export interface GroupboxDef {
+  readonly _side: 'left' | 'right'
+  readonly _name: string
+  readonly _type: 'groupbox'
+}
+
+/**
+ * Declare a groupbox in a page column.
+ *
+ * Groupboxes are arranged into two columns: `'left'` and `'right'`.
+ * Multiple groupboxes on the same side stack vertically.
+ * The `mount` option embeds a `defineComponent` return value.
+ *
+ * @param side  Column placement: `'left'` or `'right'`
+ * @param name  Display name shown as the groupbox header
+ * @param opts  `icon` required; optional `mount`, `separator`, `compatExclude`
+ *
+ * @example
+ * groupbox('left', 'Kill Aura', { icon: 'crosshair', mount: KillAura })
+ * groupbox('right', 'Aim', {
+ *   icon: 'target',
+ *   mount: AimAssist,
+ *   separator: 'Aim Assistance',
+ * })
+ */
+export declare function groupbox(
+  side: 'left' | 'right',
+  name: string,
+  opts: GroupboxOpts,
+): GroupboxDef
+
+// ── Widgets ────────────────────────────────────────────────────────────────────
+
+/** Options for `toggle`. */
+export interface ToggleOpts {
+  /** Default value shown before the user interacts. */
+  default?: boolean
+  /** Tooltip text shown on hover. */
+  tooltip?: string
+}
+
+/** Toggle widget definition — checkbox bound to a `Signal<boolean>`. */
+export interface ToggleDef extends WidgetDef {
+  bind(signal: Signal<boolean>): this
+}
+
+/**
+ * Toggle widget — maps to a checkbox in Linoria / WindUI.
+ *
+ * Use `.bind(signal)` to connect it to a `Signal<boolean>` from `@pulse/core`.
+ * The widget reads the signal's current value as its initial state and
+ * writes back on every user interaction.
+ *
+ * @param label  Text shown next to the checkbox
+ * @param opts   Optional default value and tooltip
+ *
+ * @example
+ * const enabled = signal(false)
+ * toggle('Kill Aura').bind(enabled)
+ * toggle('Silent Aim', { default: false, tooltip: 'Requires executor support' }).bind(silent)
+ */
+export declare function toggle(label: string, opts?: ToggleOpts): ToggleDef
+
+/** Options for `slider`. */
+export interface SliderOpts {
+  /** Minimum value (inclusive). */
+  min?:     number
+  /** Maximum value (inclusive). */
+  max?:     number
+  /** Step size between ticks. */
+  step?:    number
+  /** Default numeric value. */
+  default?: number
+  /** Unit suffix appended to the displayed value (e.g. `' ms'`, `' studs/s'`). */
+  suffix?:  string
+  /** Tooltip text shown on hover. */
+  tooltip?: string
+}
+
+/** Slider widget definition — numeric range control bound to a `Signal<number>`. */
+export interface SliderDef extends WidgetDef {
+  bind(signal: Signal<number>): this
+}
+
+/**
+ * Slider widget — numeric range input.
+ *
+ * @param label  Text label shown above the slider
+ * @param opts   `min`, `max`, `step`, `default`, `suffix`, `tooltip`
+ *
+ * @example
+ * const range = signal(50)
+ * slider('Range', { min: 1, max: 500, suffix: ' studs' }).bind(range)
+ *
+ * const delay = signal(200)
+ * slider('Delay', { min: 0, max: 1000, step: 10, suffix: ' ms' }).bind(delay)
+ */
+export declare function slider(label: string, opts?: SliderOpts): SliderDef
+
+/** Options for `dropdown`. */
+export interface DropdownOpts {
+  /** Available choices. */
+  options:  string[]
+  /** Default selected option (must be in `options`). */
+  default?: string
+  /** Tooltip text shown on hover. */
+  tooltip?: string
+}
+
+/** Dropdown widget definition — bound to a `Signal<string>`. */
+export interface DropdownDef extends WidgetDef {
+  bind(signal: Signal<string>): this
+}
+
+/**
+ * Dropdown widget — selectable list of options.
+ *
+ * @example
+ * const mode = signal('Distance')
+ * dropdown('Sort mode', {
+ *   options: ['Distance', 'Health', 'Name'],
+ *   default: 'Distance',
+ * }).bind(mode)
+ */
+export declare function dropdown(label: string, opts: DropdownOpts): DropdownDef
+
+/** Options for `button`. */
+export interface ButtonOpts {
+  /** Tooltip text shown on hover. */
+  tooltip?: string
+}
+
+/** Button widget definition — fires `onClick` when clicked; no signal binding. */
+export interface ButtonDef extends WidgetDef {
+  onClick(handler: () => void): this
+}
+
+/**
+ * Button widget — triggers a callback on click.
+ *
+ * @example
+ * button('Teleport to waypoint').onClick(() => teleport(waypoint()))
+ * button('Reset config').onClick(() => { enabled.set(false); range.set(50) })
+ */
+export declare function button(label: string, opts?: ButtonOpts): ButtonDef
+
+/** Options for `keybind`. */
+export interface KeybindOpts {
+  /** Default key. Use Roblox `Enum.KeyCode` value name, e.g. `'X'`, `'F'`. */
+  default?: string
+  /** Tooltip text shown on hover. */
+  tooltip?: string
+}
+
+/** Keybind widget definition — bound to a `Signal<string>`. */
+export interface KeybindDef extends WidgetDef {
+  bind(signal: Signal<string>): this
+}
+
+/**
+ * Keybind widget — lets the user rebind a hotkey.
+ *
+ * @example
+ * const key = signal('X')
+ * keybind('Toggle key', { default: 'X' }).bind(key)
+ */
+export declare function keybind(label: string, opts?: KeybindOpts): KeybindDef
+
+/** Label widget — static non-interactive text displayed in the groupbox. */
+export interface LabelDef extends WidgetDef {}
+
+/**
+ * Label widget — displays static text. No signal binding.
+ *
+ * @example
+ * label('Requires executor with drawing API')
+ */
+export declare function label(text: string): LabelDef
+
+/** Paragraph widget — static multi-line text block. */
+export interface ParagraphDef extends WidgetDef {}
+
+/**
+ * Paragraph widget — displays a titled text block. No signal binding.
+ *
+ * @example
+ * paragraph('How to use', 'Enable, then aim at a player and press the hotkey.')
+ */
+export declare function paragraph(title: string, body: string): ParagraphDef

package/package.json

@@ -0,0 +1,22 @@
+{
+  "name": "@rb-pulse/ui",
+  "version": "1.2.24",
+  "description": "Pulse framework — page, groupbox, and widget TypeScript API",
+  "main": "./index.ts",
+  "types": "./index.ts",
+  "files": [
+    "index.ts",
+    "*.d.ts"
+  ],
+  "keywords": [
+    "roblox",
+    "pulse",
+    "lua",
+    "typescript-to-lua",
+    "ui"
+  ],
+  "license": "MIT",
+  "devDependencies": {
+    "@rb-pulse/core": "1.2.24"
+  }
+}