feat(select): defineExpose some methods & refs (#314)

TotomInc · web-flow · commit 379fc7a03491 · 2025-09-08T08:21:23.000+02:00
* chore(cursor): add cursor rules * feat(select): defineExpose some methods & refs #313
diff --git a/.cursor/rules/comments.mdc b/.cursor/rules/comments.mdc
@@ -0,0 +1,53 @@
+---
+alwaysApply: true
+---
+
+# Scannable Code Guidelines/Separating Concerns.
+
+## Core Principle
+
+Code should be scannable through proper abstraction, not comments. Use variables and helper functions to make intent clear at a glance.
+
+## Good Scannable Code
+
+- Extract complex logic into well-named variables
+- Create helper functions for multi-step operations
+- Use descriptive names that explain intent
+
+Examples:
+
+```javascript
+// ✅ Scannable: Intent is clear from variable names
+const isValidUser = user.isActive && user.hasPermissions;
+const shouldProcessPayment = amount > 0 && !order.isPaid;
+
+// ✅ Scannable: Complex logic extracted to helper
+const searchParams = buildFreesoundSearchParams({ query, filters, pagination });
+const transformedResults = transformFreesoundResults({ rawResults });
+```
+
+## Bad Unscannable Code
+
+Avoid:
+
+```javascript
+// ❌ Hard to scan: What does this condition mean?
+if (type === "effects" || !type) {
+  params.append("filter", "duration:[* TO 30.0]");
+  params.append("filter", `avg_rating:[${min_rating} TO *]`);
+  if (commercial_only) {
+    params.append("filter", 'license:("Attribution" OR "Creative Commons 0")');
+  }
+}
+
+// ❌ Hard to scan: Complex ternary
+const sortParam = query
+  ? sort === "score"
+    ? "score"
+    : `${sort}_desc`
+  : `${sort}_desc`;
+```
+
+## Rule
+
+Make code scannable by extracting intent into variables and helper functions. If you need to think about what code does, extract it. The reader should understand the flow without diving into implementation details.
diff --git a/.cursor/rules/implementing-features-fixes.mdc b/.cursor/rules/implementing-features-fixes.mdc
@@ -0,0 +1,68 @@
+---
+alwaysApply: true
+description: End-to-end flow for implementing features and bug fixes using AI. Enforces playground demos, strict type-safety, tests, successful builds, and documentation updates.
+---
+
+## Implementing Features & Fixes (AI Playbook)
+
+Use this checklist for every feature or bug fix. Do not skip steps. Commands assume npm.
+
+### 1. Write or update tests first
+- **Where**: colocate tests in `src/*.spec.ts` (see existing examples like `src/Select.spec.ts`).
+- **Run tests**: `npm run test`
+  - Uses JSDOM and coverage settings from [vitest.config.ts](mdc:vitest.config.ts).
+- **Adapt existing tests** when changing behavior; add new tests for new props/events/slots.
+
+### 2. Enforce type-safety (no ts-ignore)
+- **Run type-check**: `npm run type-check`
+- **Rule**: no `@ts-ignore` or `// @ts-expect-error`. Fix types instead.
+- **Types locations**: update when needed
+  - Props: [src/types/props.ts](mdc:src/types/props.ts)
+  - Options: [src/types/option.ts](mdc:src/types/option.ts)
+  - Slots: [src/types/slots.ts](mdc:src/types/slots.ts)
+- Prefer extracting complex logic into helpers (see [src/lib/*](mdc:src/lib)) to keep components scannable.
+
+### 3. Add a Playground demo (for new features)
+- **Create demo component** under `playground/demos/YourFeature.vue`.
+- **Register route** in [playground/main.ts](mdc:playground/main.ts)
+  - Import your demo and add a `{ path: "/your-feature", component: YourFeature }` route.
+- **Add navigation link** in [playground/PlaygroundLayout.vue](mdc:playground/PlaygroundLayout.vue)
+  - Append to `links`: `{ value: "/your-feature", label: "Your Feature" }`.
+- **Run playground**: `npm run dev:playground` and manually verify the UX.
+
+### 4. Build must pass (no early exits)
+- **Run build**: `npm run build`
+  - This runs `type-check` and then `vite build` via `build-only`.
+  - Fix all errors; do not bypass checks. Do not introduce build-time warnings that indicate type holes.
+- Output is generated in `dist/` (do not edit `dist/` by hand).
+
+### 5. Documentation (new features or behavior changes)
+- **Add a docs page** under `docs/demo/*.md` when showcasing a new capability (see existing demos in `docs/demo/`).
+- **Update reference docs** if applicable:
+  - Getting started: [docs/getting-started.md](mdc:docs/getting-started.md)
+  - Props: [docs/props.md](mdc:docs/props.md)
+  - Events: [docs/events.md](mdc:docs/events.md)
+  - Slots: [docs/slots.md](mdc:docs/slots.md)
+  - Options: [docs/options.md](mdc:docs/options.md)
+  - Styling: [docs/styling.md](mdc:docs/styling.md)
+  - TypeScript: [docs/typescript.md](mdc:docs/typescript.md)
+- **Preview docs**: `npm run docs:dev` and ensure navigation from [docs/index.md](mdc:docs/index.md) remains coherent.
+- **Validate docs build**: `npm run docs:build`.
+
+### 6. Linting
+- **Run**: `npm run lint`
+- **Auto-fix**: `npm run lint:fix` (then re-run `npm run lint`).
+
+### 7. PR readiness checklist
+- Tests added/updated and `npm run test` passes.
+- `npm run type-check` passes with zero `@ts-ignore`.
+- New demo added in `playground/` (if new feature) and manually verified via `npm run dev:playground`.
+- `npm run build` completes without errors (no early exit).
+- Docs added/updated and `npm run docs:build` passes.
+- Code is scannable: complex logic extracted into helpers under `src/lib/` and meaningful names used.
+
+### Useful references
+- Package scripts: [package.json](mdc:package.json)
+- Test config: [vitest.config.ts](mdc:vitest.config.ts)
+- Playground router: [playground/main.ts](mdc:playground/main.ts)
+- Playground layout links: [playground/PlaygroundLayout.vue](mdc:playground/PlaygroundLayout.vue)
diff --git a/.cursor/rules/separation-of-concerns.mdc b/.cursor/rules/separation-of-concerns.mdc
@@ -0,0 +1,35 @@
+---
+alwaysApply: true
+---
+
+# Comment Guidelines
+
+## Good Comments (Human-style)
+- Explain WHY, not WHAT
+- Document non-obvious behavior or edge cases
+- Warn about performance implications or side effects
+- Explain business logic that isn't clear from code
+
+Examples:
+```javascript
+// transfer, not copy; sender buffer detaches
+// satisfies: check shape; keep literals  
+// keep multibyte across chunks
+// timingSafeEqual throws on length mismatch
+```
+
+## Bad Comments (AI-style)
+- Don't explain what the code literally does
+- Don't add changelog-style comments in code
+- Don't comment every line or obvious operations
+
+Avoid:
+```javascript
+// Prevent duplicate initialization
+// Check if project is already loaded  
+// Mark as initializing to prevent race conditions
+// (changed from blah to blah)
+```
+
+## Rule
+Only add comments when there's genuinely non-obvious behavior, performance considerations, or business logic that needs context. Code should be self-documenting through naming and structure.
diff --git a/.cursor/rules/ultracite.mdc b/.cursor/rules/ultracite.mdc
@@ -0,0 +1,35 @@
+---
+alwaysApply: true
+---
+
+# Comment Guidelines
+
+## Good Comments (Human-style)
+- Explain WHY, not WHAT
+- Document non-obvious behavior or edge cases
+- Warn about performance implications or side effects
+- Explain business logic that isn't clear from code
+
+Examples:
+```javascript
+// transfer, not copy; sender buffer detaches
+// satisfies: check shape; keep literals  
+// keep multibyte across chunks
+// timingSafeEqual throws on length mismatch
+```
+
+## Bad Comments (AI-style)
+- Don't explain what the code literally does
+- Don't add changelog-style comments in code
+- Don't comment every line or obvious operations
+
+Avoid:
+```javascript
+// Prevent duplicate initialization
+// Check if project is already loaded  
+// Mark as initializing to prevent race conditions
+// (changed from blah to blah)
+```
+
+## Rule
+Only add comments when there's genuinely non-obvious behavior, performance considerations, or business logic that needs context. Code should be self-documenting through naming and structure.
diff --git a/.cursor/rules/writing-scannable-code.mdc b/.cursor/rules/writing-scannable-code.mdc
@@ -0,0 +1,53 @@
+---
+alwaysApply: true
+---
+
+# Scannable Code Guidelines/Separating Concerns.
+
+## Core Principle
+
+Code should be scannable through proper abstraction, not comments. Use variables and helper functions to make intent clear at a glance.
+
+## Good Scannable Code
+
+- Extract complex logic into well-named variables
+- Create helper functions for multi-step operations
+- Use descriptive names that explain intent
+
+Examples:
+
+```javascript
+// ✅ Scannable: Intent is clear from variable names
+const isValidUser = user.isActive && user.hasPermissions;
+const shouldProcessPayment = amount > 0 && !order.isPaid;
+
+// ✅ Scannable: Complex logic extracted to helper
+const searchParams = buildFreesoundSearchParams({ query, filters, pagination });
+const transformedResults = transformFreesoundResults({ rawResults });
+```
+
+## Bad Unscannable Code
+
+Avoid:
+
+```javascript
+// ❌ Hard to scan: What does this condition mean?
+if (type === "effects" || !type) {
+  params.append("filter", "duration:[* TO 30.0]");
+  params.append("filter", `avg_rating:[${min_rating} TO *]`);
+  if (commercial_only) {
+    params.append("filter", 'license:("Attribution" OR "Creative Commons 0")');
+  }
+}
+
+// ❌ Hard to scan: Complex ternary
+const sortParam = query
+  ? sort === "score"
+    ? "score"
+    : `${sort}_desc`
+  : `${sort}_desc`;
+```
+
+## Rule
+
+Make code scannable by extracting intent into variables and helper functions. If you need to think about what code does, extract it. The reader should understand the flow without diving into implementation details.
diff --git a/docs/typescript.md b/docs/typescript.md
@@ -165,3 +165,114 @@ const roleOptions = [
   />
 </template>
 ```
+
+## Component ref and exposed API
+
+The Vue3 Select component exposes several refs and methods through `defineExpose()` for programmatic control. This provides a type-safe way to interact with the component instance.
+
+### Available exposed properties
+
+```ts
+type ExposedAPI = {
+  // DOM element refs
+  inputRef: Ref<HTMLInputElement | undefined>;
+  containerRef: Ref<HTMLDivElement | undefined>;
+
+  // Control methods
+  openMenu: () => void;
+  closeMenu: () => void;
+  toggleMenu: () => void;
+  clear: () => void;
+};
+```
+
+### Accessing the component ref
+
+Use template refs to access the exposed API:
+
+```vue
+<script setup lang="ts">
+import { nextTick, ref } from "vue";
+import VueSelect from "vue3-select-component";
+
+const selectRef = ref<InstanceType<typeof VueSelect>>();
+const selectedValue = ref<string | null>(null);
+
+const options = [
+  { label: "Option 1", value: "1" },
+  { label: "Option 2", value: "2" },
+];
+
+// Focus the input programmatically
+const focusSelect = async () => {
+  await nextTick();
+  selectRef.value?.inputRef?.focus();
+};
+
+// Open the dropdown menu
+const openDropdown = () => {
+  selectRef.value?.openMenu();
+};
+
+// Clear the selection
+const clearSelection = () => {
+  selectRef.value?.clear();
+};
+</script>
+
+<template>
+  <VueSelect
+    ref="selectRef"
+    v-model="selectedValue"
+    :options="options"
+    placeholder="Select an option"
+  />
+
+  <button @click="focusSelect">
+    Focus Input
+  </button>
+  <button @click="openDropdown">
+    Open Menu
+  </button>
+  <button @click="clearSelection">
+    Clear
+  </button>
+</template>
+```
+
+### Type safety with multi-select
+
+When using multi-select, ensure proper typing:
+
+```vue
+<script setup lang="ts">
+import type { Option } from "vue3-select-component";
+import { ref } from "vue";
+import VueSelect from "vue3-select-component";
+
+type UserOption = Option<number>;
+
+const selectRef = ref<InstanceType<typeof VueSelect<UserOption, number>>>();
+const selectedUsers = ref<number[]>([]);
+
+const userOptions: UserOption[] = [
+  { label: "Alice", value: 1 },
+  { label: "Bob", value: 2 },
+];
+</script>
+
+<template>
+  <VueSelect
+    ref="selectRef"
+    v-model="selectedUsers"
+    :options="userOptions"
+    :is-multi="true"
+  />
+</template>
+```
+
+### Best practices
+
+- Always use `nextTick()` when accessing DOM elements after component mounting
+- Check for element existence before calling methods: `selectRef.value?.inputRef?.focus()`
+- Type the ref with `InstanceType<typeof VueSelect>` for full TypeScript support
diff --git a/src/Select.spec.ts b/src/Select.spec.ts
diff --git a/src/Select.vue b/src/Select.vue
