Review Component

Review a BEEQ Component

When to Use

• Before opening a PR for a new or modified bq-* component
• Reviewing a PR that adds or modifies a bq-* component
• Auditing an existing component for guideline compliance
• Self-checking a component before submitting for review
• When a component "feels off" and you want a holistic check across all dimensions.

Procedure

1. Load the instruction files

Read these before evaluating:

• StencilJS instructions
• Styles instructions
• Accessibility instructions
• Testing instructions

2. Read the component files

Read all files for the component:

• bq-<name>.tsx — component logic
• bq-<name>.types.ts — type definitions
• scss/bq-<name>.scss — styles
• scss/bq-<name>.variables.scss — CSS custom properties
• __tests__/bq-<name>.e2e.tsx — E2E tests
• _storybook/bq-<name>.stories.tsx — Storybook stories

3. Evaluate each category

For each category below, mark ✅ pass, ⚠️ needs improvement, or ❌ fail, and list specific issues.

---

A. File Structure & Section Order

• Sections appear in the exact prescribed order (Own Properties → @Element() → @State() → @Prop() → @Watch() → @Event() → lifecycle → @Listen() → public methods → private methods → render())
• Sections header comments are present even if the section is empty
• render() is the last method in the class
• shadow: true is set (or delegatesFocus: true only when needed)
• formAssociated: true is present only when the component submits form data
• No # private fields — only private keyword

B. Naming Conventions

• Tag uses bq- prefix and kebab-case
• Class name is Bq<Name> in PascalCase
• Events are camelCase with bq prefix (e.g. bqChange, bqClick)
• Event handler methods are prefixed with handle (e.g. handleClick)
• State variables, props, and methods are camelCase
• Constants and enum values are ALL_CAPS
• Private methods use arrow functions with the private keyword
• All public methods are async
• Type parameters are prefixed with T (e.g. TButtonSize)
• SCSS class names follow BEM

C. JSDoc Completeness

• Component-level JSDoc block present above @Component({})
• @example, @documentation, @status, @dependency tags present
• Every @Prop() documented with @attr in component JSDoc
• Every @Event() has JSDoc on the property and @event in component JSDoc
• Every @Method() has JSDoc with @param and @returns
• Every @Prop() has an inline JSDoc comment
• Every slot has @slot in component JSDoc
• Every shadow part has @part in component JSDoc
• Every CSS custom property has @cssprop in component JSDoc

D. Props & Events

• Props with fixed allowed values use validatePropValue() + @Watch()
• Optional boolean props (prop?: boolean) should not also declare = false; use either an optional boolean or a required boolean with an explicit false default, depending on the intended API shape
• String props should not default to undefined if they are required.
• Styling-related props use reflect: true
• No prop defaults that contradict the type (e.g. undefined typed as string)
• Events use typed EventEmitter<T> (not EventEmitter<any>)
• Events bubble correctly (check bubbles, cancelable options if needed)