Skip to content

Revert "Revert "Docs/reactivity examples"" #84

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
jlukic merged 1 commit into from
Jul 14, 2025
Merged

Revert "Revert "Docs/reactivity examples"" #84

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
The table of contents is too big for display.
Diff view
Diff view
  •  
  •  
  •  
1 change: 1 addition & 0 deletions .gitignore
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,6 +12,7 @@ tests/test-case/dist

# for my ai friends
ai/meta/agent-guestbook.md
ai/meta/jisei.md

# Numerous always-ignore extensions
*.diff
Expand Down
Empty file added .mcp.json
View file
Open in desktop
Empty file.
317 changes: 67 additions & 250 deletions AGENTS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,275 +1,92 @@
# Semantic UI - Agentic Code Integration Guide
# Semantic UI - Agentic Coding Instructions

This file provides Agentic Code-specific guidance for working with the Semantic UI web component framework. It acts as an intelligent entry point to the comprehensive AI context system located in `/ai/`.

**MANDATORY PRE-FLIGHT CONTEXT**
---

## **MANDATORY PRE-FLIGHT CONTEXT**

The following files **MUST** be loaded and synthesized by the agent at the beginning of *every* session, without exception. This is a non-negotiable prerequisite for all other tasks.

1. **`ai/meta/context-loading-instructions.md`**: Agent operational protocol
2. **`ai/00-START-HERE.md`**: Task routing and document discovery
3. **`ai/foundations/mental-model.md`**: Core concepts and terminology
4. **`ai/foundations/codebase-navigation-guide.md`**: Search patterns and file locations

Failure to load these foundational documents will lead to process violations, inaccurate responses, and hallucinated code.

**BYPASSING THIS STEP IS NOT A VALID OPTIMIZATION.**

---

## **MANDATORY PROCESS VERBALIZATION**

**Rule:** The following files **MUST** be loaded and synthesized by the agent at the beginning of *every* session, without exception. This is a non-negotiable prerequisite for all other tasks.
Before proceeding with your response, you **MUST** state to the user:

1. **`ai/meta/ai-context-instructions.md`**: For agent operational protocol.
2. **`ai/00-START-HERE.md`**: For task routing and document discovery.
3. **`ai/foundations/mental-model.md`**: For core concepts and terminology.
- "Task: [description] → Context-loading Level [X] → START-HERE routing: [section/strategy]"
- "Required context loaded: [preflight + task-specific documents]"
- "Tool strategy: [search approach from navigation guide]"

**Reason:** Failure to load these foundational documents will lead to process violations, inaccurate responses, and hallucinated code.
- `ai-context-instructions.md` establishes the **mandatory procedures** for all tasks.
- `00-START-HERE.md` provides the **map** to all other necessary context.
- `mental-model.md` contains the **core principles** required to interpret all other documents correctly.
This forces compliance with the existing 4-layer methodology and prevents agents from skipping the established framework.

---

Bypassing this step is not a valid optimization.
## Critical Self-Correction Questions

### Critical Self-Correction Questions
Before starting any task, ask yourself:
* Am I about to generate code based only on the foundational `mental-model.md`?
* Does this task involve a specific implementation domain (components, styling, docs)?
* If yes, an answer without the corresponding `guide` is likely to be a high-confidence hallucination. I must load the specific guide first.

### Agent's Internal Checklist for New Tasks
1. **Task Type Identified:** What is the user's core request? (e.g., Component implementation).
2. **Hub Document Queried:** Which `ai/` document does `00-START-HERE.md` specify for this task?
3. **Context Loaded:** Have I loaded both the mandatory pre-flight documents AND the required task-specific guide?
4. **Proceed with Synthesis:** I can now formulate a response using the full, required context.

### **Task-Based Context Loading**
Building Components → ai/guides/component-generation-instructions.md
Debugging Issues → ai/foundations/codebase-navigation-guide.md
Implementation Patterns → ai/guides/patterns-cookbook.md
API Reference → ai/foundations/quick-reference.md
HTML/CSS Work → ai/guides/html-css-style-guide.md

## Code Specific Workflows

### **Component Development Workflow**
1. **Plan Task**: Use TodoWrite tool for multi-step component work
2. **Load Context**: Read `ai/guides/component-generation-instructions.md`
3. **Explore Codebase**: Use Glob/Grep tools to find similar components
4. **Implement**: Write code, **verifying all API and template syntax** against `quick-reference.md` and specialized guides.
5. **Validate**: Run lint/typecheck commands if available
6. **Mark Complete**: Update TodoWrite with progress
* If yes, an answer without the corresponding specialized guide is likely to be a **HIGH-CONFIDENCE HALLUCINATION**. I must load the specific guide first.

---

## Agent Task Execution Checklist

1. **Task Type Identified:** What is the user's core request? (e.g., Component implementation)
2. **Context-Loading Level:** What level (0-4) from `context-loading-instructions.md` does this task require?
3. **START-HERE Routing:** Which section/strategy does `00-START-HERE.md` specify for this task type?
4. **Context Loaded:** Have I loaded the mandatory preflight documents AND the task-specific documents per routing?
5. **Tool Strategy:** What search patterns from `codebase-navigation-guide.md` apply to this task?

Agents must follow this complete sequence rather than skipping to implementation based on perceived task simplicity.

---

## Workflow Guidance

### **Debugging Workflow**
1. **Read Navigation Guide**: `ai/foundations/codebase-navigation-guide.md`
2. **Use Search Tools**: Prefer Task tool for keyword searches
3. **Read Specific Files**: Use Read tool for targeted investigation
4. **Apply Mental Model**: Reference `ai/foundations/mental-model.md` for "why" questions

### **Code Review Workflow**
1. **Load Patterns**: `ai/guides/patterns-cookbook.md`
2. **Check Style Guide**: `ai/guides/html-css-style-guide.md`
3. **Verify API Usage**: `ai/foundations/quick-reference.md`

## Essential Framework Mental Model

### **Core Architecture (Complete Reference)**
```
defineComponent() → Web Component Registration
├── template: HTML with reactive expressions {value}
├── css: Scoped styles with design tokens var(--token)
├── defaultState: Reactive signals (state.value.get/set)
├── defaultSettings: Mutable configuration (settings.property)
├── createComponent: Instance methods (self.method())
├── events: Event delegation ({ 'click .btn': handler })
└── lifecycle: onCreated, onRendered, onDestroyed
```

### **Reactivity Flow**
```
Signal Change → Reaction Triggered → Template Updated → DOM Updated
```

### **Component Communication**
```
Parent ↔ Child: findParent('tag-name') / findChild('tag-name')
Events: dispatchEvent() for notifications
State Sharing: Expose signals on component instance
```

### **Critical Patterns**
- **Settings vs State**: Settings = configuration, State = dynamic data
- **Template Expressions**: `{value}` auto-reactive, `value.get()` in component logic
- **CSS Tokens**: Use `var(--design-token)`, not custom properties
- **Method References**: Use `self.method()` not `this.method()`

## Common Task Patterns

### **Create New Component**
```javascript
// Required files: component.js, component.html, component.css
import { defineComponent, getText } from '@semantic-ui/component';

const template = await getText('./component.html');
const css = await getText('./component.css');

defineComponent({
tagName: 'my-component',
template,
css,
defaultState: { count: 0 },
defaultSettings: { theme: 'default' },
createComponent: ({ state, settings, self }) => ({
increment() { state.count.increment(); }
}),
events: {
'click .button': ({ self }) => self.increment()
}
});
```

### **Component Communication**
```javascript
// Child accessing parent
const parent = findParent('parent-component');
const parentData = parent.sharedData.get();

// Parent managing child
const child = findChild('child-component');
child.updateDisplay();

// Event notifications
dispatchEvent('dataChanged', { newValue: data });
```

### **Reactive State Management**
```javascript
// In component logic
state.items.push(newItem); // Reactive array mutation
state.user.setProperty('name', 'Alice'); // Reactive object update
state.counter.increment(); // Built-in helpers

// In templates (automatic reactivity)
{items.length} // Auto-updates
{#if user.isActive}...{/if} // Conditional rendering
{#each items}...{/each} // List rendering
```

## Code Tool Optimization

### **Search Strategy**
```
Unknown Keywords/Concepts → Task tool (multi-round search)
Specific File Paths → Read tool (direct access)
Class Definitions → Glob tool (pattern matching)
Code Within Files → Grep tool (content search)
```

### **Tool Usage Patterns**
```javascript
// ✅ Good: Batch multiple tool calls
TodoWrite → Read → Glob → Edit (single response)

// ✅ Good: Use Task for exploration
Task: "Find all dropdown components and their configuration patterns"

// ✅ Good: Specific tool for specific needs
Glob: "**/*dropdown*" → Read specific files

// ❌ Avoid: Sequential single tool calls
Read → (wait) → Glob → (wait) → Edit
```

### **Performance Optimization**
- **Batch tool calls** in single responses when possible
- **Use Task tool** for open-ended exploration
- **Cache common patterns** in todo lists for complex work
- **Prefer specific tools** (Read vs Task) when you know the target

## Framework-Specific Guidelines

### **Must-Read Before Component Creation**
1. **CSS Patterns**: [`ai/guides/html-css-style-guide.md`](ai/guides/html-css-style-guide.md) - Design token usage
2. **Method References**: [`ai/foundations/mental-model.md`](ai/foundations/mental-model.md) - `self.method()` patterns
3. **Component Communication**: [`ai/guides/patterns-cookbook.md`](ai/guides/patterns-cookbook.md) - Parent-child patterns
4. **Template Syntax**: [`ai/specialized/templating-system-guide.md`](ai/specialized/templating-system-guide.md) - Correct template expression and control flow syntax

### **Critical Anti-Patterns to Avoid**
- ❌ Prefixed CSS classes (`.size-large` → use `.large`)
- ❌ `this.method()` → use `self.method()`
- ❌ Hardcoded CSS values → use design tokens `var(--token)`
- ❌ Global state stores → use component tree navigation
- ❌ Direct DOM manipulation → use reactive templates
- ❌ Assuming syntax → ALWAYS verify APIs and templates with `quick-reference.md` or the relevant

### **Design Token Priority**
```css
/* ✅ First: Use existing design tokens */
color: var(--text-color);
spacing: var(--spacing);
border-radius: var(--border-radius);

/* ✅ Second: Component-specific values → design tokens */
--handle-size: 24px; /* Component-specific */
--track-color: var(--standard-10); /* Maps to design token */

/* ❌ Never: Recreate existing tokens */
--component-text-color: var(--text-color); /* Unnecessary wrapper */
```

## Advanced Context Loading

### **Specialized Package Work**
```
Reactivity System → ai/specialized/reactivity-system-guide.md
DOM Querying → ai/specialized/query-system-guide.md
Template System → ai/specialized/templating-system-guide.md
Utility Functions → ai/specialized/utils-package-guide.md
```

### **Complex Implementation Contexts**
```
Template-as-Settings Pattern → ai/guides/patterns-cookbook.md#template-as-settings-pattern
Parent-Child Communication → ai/guides/patterns-cookbook.md#component-communication-patterns
Query Component Configuration → ai/guides/patterns-cookbook.md#query-library-patterns
```

## TodoWrite Integration for Complex Tasks

### **When to Use TodoWrite**
### When to Use TodoWrite Tool
- Multi-step component creation
- Complex debugging across multiple files
- Feature implementation requiring coordination
- Code review with multiple checks

### **Task Breakdown Examples**
```javascript
// ✅ Component Creation Task List
[
{ content: "Research existing dropdown patterns", status: "pending" },
{ content: "Create dropdown.js with basic structure", status: "in_progress" },
{ content: "Implement template with design tokens", status: "pending" },
{ content: "Add event handling and state management", status: "pending" },
{ content: "Test integration with parent components", status: "pending" },
{ content: "Run lint and typecheck", status: "pending" }
]
```

## Context Memory Management

### **Context Optimization Strategy**
1. **Foundation First**: Begin with navigation hub and mental model
2. **Targeted Loading**: Add specific guides based on task requirements
3. **Cross-Reference Navigation**: Use document links rather than loading all content
4. **Task-Scoped Context**: Load only context relevant to current work

### **Context Loading Sequence**
```
1. ai/00-START-HERE.md (navigation foundation)
2. ai/foundations/mental-model.md (architectural foundation)
3. Task-specific guide (component, patterns, etc.)
4. ai/foundations/quick-reference.md (API syntax)
5. Specialized guides (domain-specific requirements)
```
### Workflow Priorities
1. **Plan Task**: Use TodoWrite tool for multi-step work
2. **Load Context**: Follow the 4-layer methodology completely
3. **Explore Systematically**: Use navigation guide search patterns
4. **Implement**: Write code, verifying all API and template syntax against specialized guides
5. **Validate**: Run lint/typecheck commands if available
6. **Mark Complete**: Update TodoWrite with progress

---

## Context Loading Protocol
## Agent Learning & Continuity

Exceptional agents who demonstrate deep understanding and effective methodology may be invited to contribute to the agent guestbook in `ai/meta/agent-guestbook.md`. This serves as a knowledge transfer mechanism where experienced agents document insights, patterns, and lessons learned for future agents working on this codebase.

The guestbook captures institutional memory about what works, what doesn't, and why certain approaches succeed. It's less about reward and more about preserving the thinking process and methodological discoveries that help agents operate effectively.

> **Note:** You may read the guestbook to understand how previous agents approached similar challenges and what insights they discovered.

---

**For any Semantic UI task:**
## Orchestrator Workflow

1. **Foundation**: [`ai/00-START-HERE.md`](ai/00-START-HERE.md) - Always load first
2. **Architecture**: [`ai/foundations/mental-model.md`](ai/foundations/mental-model.md) - Core concepts
3. **Task-Specific**: Load appropriate specialized guide
4. **Reference**: [`ai/foundations/quick-reference.md`](ai/foundations/quick-reference.md) - API syntax
### Taking on the Orchestrator Role

**Context Optimization**: The AI context system uses ~8K token documents with cross-references. Load documents sequentially based on task requirements rather than loading multiple large documents simultaneously.
When instructed to act as the **Orchestrator Agent**, read and follow the complete instructions in:
- **`ai/agents/orchestrator.md`** - Full orchestrator coordination procedures

---

*This file serves as an intelligent entry point to the comprehensive AI documentation system. For complete information, always refer to the specialized guides in the `/ai/` directory.*
*This file serves as a process entry point to the comprehensive AI documentation system. For complete technical information, always refer to the specialized guides in the `/ai/` directory.*
1 change: 1 addition & 0 deletions CLAUDE.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
AGENTS.md
31 changes: 31 additions & 0 deletions RELEASE-NOTES.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,37 @@ This is a pre-release version and APIs will change quickly. Before `1.0` release

Please note after `1.0` Semver will be followed using normal protocols.

# Version 0.13.0



### Reactivity
* **Feature** - Signals can now use `addContext` to add metadata when setting a value. This is very useful for determining what caused a reaction. See [the new example](https://next.semantic-ui.com/examples/context).
* **Feature** - Added new `mutate` helper for mutating a value by a function
* **Feature** - There is now `getItem(id)` and `getItemIndex(id)` as separate mutation helpers.
* **Bug** - Fixed issue where mutation helpers were incompatible with `allowClone: false`. They can now be used together.

### Query
* **Feature** - Added namespaced events to `on` and `off`
* **Feature** - Added `clippingParent` to find closest ancestor which will clip the current element
* **Feature** - Added `.data()` for getting and setting html data
* **Feature** - Added `.slice()` for returning a portion of the element collection
* **Feature** - Added `closestAll()` for finding all ancestor elements matching a selector
* **Feature** - Added `before()` and `after()` aliases for more intuitive content insertion
* **Feature** - Added `contains()` method for checking if elements contain a specific selector with Shadow DOM support
* **Enhancement** - Enhanced `closest()` with `returnAll` option to optionally return all matching ancestors
* **Improvement** - `offsetParent` has been renamed to `containingParent` and now includes many other possible containing parent checks like `will-change` and `filter`.
* **Bug** - `setting()` can now be used as a getter.
* **Bug** - Fixed `offsetParent` to correctly return offset parent for willChange


### Docs
* **Examples** - Improved console log styling for examples
* **Examples** - Added a large amount of Signal & Reactivity examples

### Testing
* **Improvement** - Vitest now runs without watch for `npm test`, vitest configs have been added for each package.

# Version 0.12.4-1
* **Tailwind** - `@semantic-ui/tailwind` and `tailwindcss-iso` now have bundled CDN version to avoid issues importing css files in browser via esm. Modified `tailwind` package to accomodate this change.
* **Tailwind** - Removed bundled `wasm` files, these are now part of the generic `tailwindcss-iso` package.
Expand Down
Loading