Added issues that are going to be tracked and will be deeply considering changes based on DX.

Co-authored-by: Copilot <copilot@github.com>
2026-05-06 00:21:13 +05:00
parent f6ae86617c
commit 0787525134
8 changed files with 1218 additions and 0 deletions
@@ -0,0 +1,51 @@
+# Component API Design Guidelines
+
+Use this when creating or evolving components so the API remains predictable.
+
+## Goals
+
+- Consistency across all components
+- Safe defaults for user content
+- Low ceremony for common use cases
+- Explicit escape hatches for advanced scenarios
+
+## Baseline API Conventions
+
+For every new component, prefer:
+
+- `className` for caller-supplied Tailwind/CSS classes
+- `attributes` for arbitrary HTML attributes (`aria-*`, `data-*`, test IDs)
+- Strongly typed semantic options where practical (enums or constants)
+- Named item records instead of tuples for complex lists
+
+## Safety Rules
+
+1. Plain text input should be encoded by default.
+2. Raw HTML should require an explicit trusted path.
+3. Never require callers to manually concatenate unsafe attribute strings for normal usage.
+
+## Documentation Rules
+
+Every component doc should include:
+
+1. Quick example
+2. All options
+3. Security notes
+4. Accessibility notes
+5. JS dependency notes (if interactive)
+6. Extension points (`className`, `attributes`)
+
+## Evolution Rules
+
+1. Prefer additive changes first.
+2. Mark old APIs as deprecated with migration examples.
+3. Remove deprecated paths only in major release.
+
+## Review Checklist
+
+- Is the API consistent with sibling components?
+- Can callers add classes without wrapper divs?
+- Can callers pass `aria-*` and `data-*` safely?
+- Are semantic options type-safe?
+- Are user-provided strings encoded by default?
+- Are interactive JS requirements documented?
@@ -0,0 +1,128 @@
+# Component API Limitations and Workarounds
+
+This page documents known limitations in the current component API and practical ways to work effectively with them.
+
+## 1) Magic String Parameters
+
+Limitation:
+- Semantic options like `variant`, `size`, and similar values are frequently string-based.
+
+What this means:
+- Typos may silently fall back to defaults.
+
+Workaround:
+- Centralize repeated literals in local constants in your feature code.
+- Prefer named arguments for readability.
+
+Example:
+
+```csharp
+private const string VariantDestructive = "destructive";
+
+var deleteButton = new Button(
+    label: "Delete",
+    variant: VariantDestructive,
+    size: "sm");
+```
+
+## 2) Extra Styling Often Requires Wrappers
+
+Limitation:
+- Not every component exposes a class extension parameter.
+
+What this means:
+- You may need wrapper elements for layout spacing, sizing, or responsive behavior.
+
+Workaround:
+- Use a minimal wrapper pattern and keep wrapper intent obvious.
+
+Example:
+
+```html
+<div class="md:max-w-sm w-full">$$SaveButton$$</div>
+```
+
+## 3) No Universal Attribute Bag
+
+Limitation:
+- Some components expose `hxAttrs`, some do not, and no shared attributes model exists yet.
+
+What this means:
+- Passing `aria-*`, `data-*`, or test selectors is inconsistent.
+
+Workaround:
+- Prefer wrapper-level attributes where possible.
+- If using raw attr strings, keep them static and explicit.
+
+## 4) No Direct "Props in .htmx Markup" Model
+
+Limitation:
+- Component/page parameterization is constructor-driven in `.htmx.cs`, not inline-props driven in `.htmx` markup.
+
+What this means:
+- Dynamic behavior is assembled in C# code-behind.
+
+Workaround:
+- Treat `.htmx` as shape and slot layout.
+- Treat `.htmx.cs` as the single source of component input logic.
+
+## 5) Raw HTML Output Requires Discipline
+
+Limitation:
+- Several components render provided strings as HTML.
+
+What this means:
+- User input must be encoded before rendering.
+
+Workaround:
+- Always encode user-provided values before `ToUtf8Bytes()`.
+
+Example:
+
+```csharp
+var safeName = System.Web.HttpUtility.HtmlEncode(userDisplayName);
+_nameData = safeName.ToUtf8Bytes();
+```
+
+## 6) Interactive Components Depend on JS Contracts
+
+Limitation:
+- Components like tabs, accordion, dialog, calendar, and toast depend on JavaScript hooks/selectors.
+
+What this means:
+- Markup can render but behave incorrectly if expected JS wiring is missing.
+
+Workaround:
+- Verify behavior after HTMX swaps.
+- Keep required data-role/class markers intact.
+
+## 7) Tuple APIs for Complex Components
+
+Limitation:
+- Some components expect tuple arrays for items/options.
+
+What this means:
+- Call sites can become harder to read and evolve.
+
+Workaround:
+- Build small local records/variables first, then map to tuples.
+
+## 8) Form API Inconsistency
+
+Limitation:
+- Form primitives do not all expose the same extension points.
+
+What this means:
+- You need per-component familiarity.
+
+Workaround:
+- Create feature-local helper methods to normalize usage patterns.
+
+## 9) Recommendation for Teams
+
+If multiple developers are contributing:
+
+1. Define local conventions for allowed variant strings.
+2. Standardize wrapper patterns (`layout wrappers`, `a11y wrappers`, `test-id wrappers`).
+3. Review for HTML encoding whenever user input is rendered.
+4. Track repeated pain points in docs/Issues for future API upgrades.