@canonical/code-standards 0.1.0 → 0.1.2

package/docs/react.md

@@ -8,7 +8,7 @@ The index.ts file must be a complete barrel export for the component folder, re-
 
 ### Do
 
-(Do) Create an index.ts file that re-exports all public APIs from the component folder.
+Create an index.ts file that re-exports all public APIs from the component folder.
 ```typescript
 // index.ts
 export { default as [MyComponent] } from './[MyComponent].js';
@@ -19,13 +19,13 @@ export { default as SubComponent } from './SubComponent.js';
 
 ### Don't
 
-(Don't) Omit the index.ts file or fail to re-export all public APIs.
+Omit the index.ts file or fail to re-export all public APIs.
 ```typescript
 // Bad: index.ts only exports default, omits types and named exports
 export { default } from './[MyComponent].js';
 ```
 
-(Don't) Use `export * from './types.js'` as it allows value exports, which is not expected for types files.
+Use `export * from './types.js'` as it allows value exports, which is not expected for types files.
 ```typescript
 // Bad: Using export * from './types.js' allows value exports, which is not allowed
 export * from './types.js';
@@ -47,7 +47,7 @@ Component CSS class names must be constructed following a specific pattern:
 
 ### Do
 
-(Do) Follow the complete pattern for class name construction.
+Follow the complete pattern for class name construction.
 ```tsx
 const componentCssClassName = "ds badge";
 
@@ -72,19 +72,19 @@ const Badge = ({
 
 ### Don't
 
-(Don't) Hardcode the base class name inside the JSX.
+Hardcode the base class name inside the JSX.
 ```tsx
 // Bad: Base class "ds badge" is hardcoded.
 <span className={["ds badge", severity, className].filter(Boolean).join(" ")}>
 ```
 
-(Don't) Place the consumer `className` prop before other classes.
+Place the consumer `className` prop before other classes.
 ```tsx
 // Bad: Consumer class is first
 <span className={[className, componentCssClassName, severity].filter(Boolean).join(" ")}>
 ```
 
-(Don't) Use string concatenation or template literals to add class names.
+Use string concatenation or template literals to add class names.
 ```tsx
 // Bad: Harder to read and maintain, vulnerable to inconsistent formatting
 <span className={`${componentCssClassName} ${severity} ${className}`}>
@@ -101,7 +101,7 @@ Component dependencies must follow a strict unidirectional flow:
 
 ### Do
 
-(Do) Place subcomponents in a `common/` folder inside the parent component directory.
+Place subcomponents in a `common/` folder inside the parent component directory.
 ```
 Card/
   ├── Card.tsx
@@ -115,7 +115,7 @@ Card/
   └── index.ts
 ```
 
-(Do) Allow subcomponents to depend on siblings or shared utilities within the same component scope.
+Allow subcomponents to depend on siblings or shared utilities within the same component scope.
 ```typescript
 // Header.tsx can import from utils/
 import { helper } from '../utils/helpers.js';
@@ -126,13 +126,13 @@ import Header from '../Header.js';
 
 ### Don't
 
-(Don't) Create dependencies that flow upwards from a subcomponent to its parent.
+Create dependencies that flow upwards from a subcomponent to its parent.
 ```typescript
 // Bad: Header.tsx in Card/common/ should not import from Card.tsx
 import Card from '../../Card.js';
 ```
 
-(Don't) Allow external components to depend on the internal structure of another component.
+Allow external components to depend on the internal structure of another component.
 ```typescript
 // Bad: AnotherComponent should not import from Card's internal common folder
 import Header from '../Card/common/Header.js';
@@ -146,7 +146,7 @@ Component folder and file naming is based on scope. Component-specific files (im
 
 ### Do
 
-(Do) Prefix component-specific files and use generic names for domain-level files.
+Prefix component-specific files and use generic names for domain-level files.
 ```
 [MyComponent]/
   ├── [MyComponent].tsx           # Component-specific
@@ -159,7 +159,7 @@ Component folder and file naming is based on scope. Component-specific files (im
 
 ### Don't
 
-(Don't) Add redundant prefixes to domain-level files.
+Add redundant prefixes to domain-level files.
 ```
 [MyComponent]/
   ├── [MyComponent].Context.tsx   # Bad: Redundant prefix
@@ -171,18 +171,21 @@ Component folder and file naming is based on scope. Component-specific files (im
 
 ## react/component/naming
 
-Components must use PascalCase naming and be descriptive of their purpose.
+Use PascalCase and descriptive names for components:
+UserProfile
+NavigationBar
+SearchResultList
 
 ### Do
 
-(Do) Use PascalCase and descriptive names for components:
+Use PascalCase and descriptive names for components:
 UserProfile
 NavigationBar
 SearchResultList
 
 ### Don't
 
-(Don't) Use non-PascalCase or unclear names:
+Use non-PascalCase or unclear names:
 userProfile
 navigation_bar
 searchresultlist
@@ -199,7 +202,7 @@ Component props must:
 
 ### Do
 
-(Do) Document props with TSDoc comments and use proper destructuring and spreading.
+Document props with TSDoc comments and use proper destructuring and spreading.
 ```typescript
 interface ButtonProps extends React.ButtonHTMLAttributes<HTMLButtonElement> {
   /** The button's text content */
@@ -229,7 +232,7 @@ const Button = ({
 
 ### Don't
 
-(Don't) Mix explicit and spread props or destructure props unnecessarily.
+Mix explicit and spread props or destructure props unnecessarily.
 ```typescript
 // Bad: Mixing explicit props with spread
 const Button = (props: ButtonProps) => (
@@ -271,7 +274,7 @@ Components that render HTML markup must extend the base HTML element props inter
 
 ### Do
 
-(Do) Extend the appropriate React HTML props interface and add component-specific props.
+Extend the appropriate React HTML props interface and add component-specific props.
 ```typescript
 export interface ButtonProps extends React.ButtonHTMLAttributes<HTMLButtonElement> {
   /** The button label */
@@ -281,7 +284,7 @@ export interface ButtonProps extends React.ButtonHTMLAttributes<HTMLButtonElemen
 
 ### Don't
 
-(Don't) Manually redefine standard HTML attributes that are already available through the base interface.
+Manually redefine standard HTML attributes that are already available through the base interface.
 ```typescript
 export interface ButtonProps {
   /** The button label */
@@ -299,7 +302,7 @@ Wrapper components must use namespaced props for inner components and accept uns
 
 ### Do
 
-(Do) Use namespaced props for inner components and unscoped props for the wrapper element.
+Use namespaced props for inner components and unscoped props for the wrapper element.
 ```tsx
 interface ThumbnailSectionProps extends SectionProps {
   /** Props for the thumbnail image */
@@ -321,7 +324,7 @@ const ThumbnailSection = ({
 
 ### Don't
 
-(Don't) Mix prop scopes between wrapper and inner components.
+Mix prop scopes between wrapper and inner components.
 ```tsx
 interface ThumbnailSectionProps {
   src: string;      // Bad: Unscoped image props
@@ -344,7 +347,7 @@ Context providers must use `Provider.tsx` as the main component file instead of
 
 ### Do
 
-(Do) Organize provider-related files by separating concerns into distinct files: place the context definition in `Context.tsx`, the provider implementation in `Provider.tsx`, and provider-specific hooks in a `hooks/` directory. Create a `hooks/useProviderState.ts` file to centrally manage the state of the provider.`
+Organize provider-related files by separating concerns into distinct files: place the context definition in `Context.tsx`, the provider implementation in `Provider.tsx`, and provider-specific hooks in a `hooks/` directory. Create a `hooks/useProviderState.ts` file to centrally manage the state of the provider.`
 ```
 [MyComponent]/
   ├── Context.tsx
@@ -361,8 +364,8 @@ Context providers must use `Provider.tsx` as the main component file instead of
       ├── types.ts
       └── useProviderState.ts
 ```
-(Do) Create the context type within `types.ts`.
 
+Create the context type within `types.ts`.
 ```typescript
 // [MyComponent]/types.ts
 /** The value of the config context */
@@ -374,8 +377,7 @@ export interface ContextOptions {
 }
 ```
 
-(Do) create the provider props type within `types.ts`, accepting `children` at a minimum and more props as needed.
-
+create the provider props type within `types.ts`, accepting `children` at a minimum and more props as needed.
 ```typescript
 // [MyComponent]/types.ts
 
@@ -386,7 +388,7 @@ export interface ProviderProps {
 }
 ```
 
-(Do) Create a `Context.tsx` file for the context definition.
+Create a `Context.tsx` file for the context definition.
 ```tsx
 // [MyComponent]/Context.tsx
 import { createContext } from "react";
@@ -397,8 +399,7 @@ const Context = createContext<ContextOptions | undefined>(undefined);
 export default Context;
 ```
 
-
-(Do) Use `Provider.tsx` as the main component file. The provider is responsible for wrapping children with the context.
+Use `Provider.tsx` as the main component file. The provider is responsible for wrapping children with the context.
 ```tsx
 // [MyComponent]/Provider.tsx
 import Context from "./Context.js";
@@ -413,7 +414,7 @@ const Provider = ({ children }: ProviderProps) => {
 export default Provider;
 ```
 
-(Do) Use `index.ts` to export the `Provider` as a named component that matches the folder name, casting it to the component type.
+Use `index.ts` to export the `Provider` as a named component that matches the folder name, casting it to the component type.
 ```typescript
 // [MyComponent]/types.ts
 import type { ReactElement } from "react";
@@ -430,7 +431,7 @@ export const [MyComponent] = Provider as [MyComponent]Component;
 export default [MyComponent];
 ```
 
-(Do) Create provider state hook types in `hooks/types.ts` for context providers.
+Create provider state hook types in `hooks/types.ts` for context providers.
 ```typescript
 // [MyComponent]/hooks/types.ts
 import type { ContextOptions, ProviderProps } from "../types.js";
@@ -442,7 +443,7 @@ export type UseProviderStateProps = Omit<ProviderProps, "children">;
 export type UseProviderStateResult = ContextOptions;
 ```
 
-(Do) Create a provider state hook implementation.
+Create a provider state hook implementation.
 ```tsx
 // [MyComponent]/hooks/useProviderState.ts
 import { useContext } from "react";
@@ -460,14 +461,14 @@ const useProviderState = ({
 
 ### Don't
 
-(Don't) Create a separate component file (e.g., `[MyComponent].tsx`) when `Provider.tsx` exists. The provider is the main component.
+Create a separate component file (e.g., `[MyComponent].tsx`) when `Provider.tsx` exists. The provider is the main component.
 ```
 [MyComponent]/
   ├── [MyComponent].tsx
   └── Provider.tsx
 ```
 
-(Don't) Nest context-related files in a `context/` subfolder.
+Nest context-related files in a `context/` subfolder.
 ```
 [MyComponent]/
   └── context/ # Unnecessary nesting
@@ -475,15 +476,14 @@ const useProviderState = ({
       └── Provider.tsx
 ```
 
-(Don't) Create multiple provider files within the same component folder.
+Create multiple provider files within the same component folder.
 ```
 [MyComponent]/
   ├── Provider.tsx
   └── AnotherProvider.tsx # Only one provider per component
 ```
 
-(Don't) Mix concerns of the Provider and its state.
-
+Mix concerns of the Provider and its state.
 ```tsx
 exort const Provider = ({ children }: ProviderProps) => {
   const [state, setState] = useState(...); // Bad: State logic mixed in
@@ -499,7 +499,7 @@ Each component must reside in its own folder, which contains all related files:
 
 ### Do
 
-(Do) Place all component-related files within a single folder named after the component.
+Place all component-related files within a single folder named after the component.
 ```bash
 [MyComponent]/
   ├── [MyComponent].tsx
@@ -512,7 +512,7 @@ Each component must reside in its own folder, which contains all related files:
 
 ### Don't
 
-(Don't) Scatter component files across different parts of the application.
+Scatter component files across different parts of the application.
 ```bash
 # Bad: Files are not co-located
 components/
@@ -540,7 +540,7 @@ Private subcomponents must remain internal to the component's implementation and
 
 ### Do
 
-(Do) Export public subcomponents by attaching them to the parent component using dot notation:
+Export public subcomponents by attaching them to the parent component using dot notation
 ```typescript
 const Item = (props: ItemProps) => { /* ... */ };
 const Accordion = (props: AccordionProps) => { /* ... */ };
@@ -548,14 +548,14 @@ Accordion.Item = Item;
 export default Accordion;
 ```
 
-(Do) Use semantic, self-descriptive names for subcomponents:
+Use semantic, self-descriptive names for subcomponents
 ```typescript
 Accordion.Item
 Card.Header
 Card.Footer
 ```
 
-(Do) Keep subcomponent nesting to a single level:
+Keep subcomponent nesting to a single level
 ```typescript
 <Card>
   <Card.Header />
@@ -565,17 +565,17 @@ Card.Footer
 
 ### Don't
 
-(Don't) Repeat the parent component name in subcomponent names:
+Repeat the parent component name in subcomponent names
 ```typescript
 Card.CardHeader = Header; // Bad: Redundant 'Card' prefix
 ```
 
-(Don't) Map a subcomponent to a different name (renaming):
+Map a subcomponent to a different name (renaming)
 ```typescript
 Card.Top = Header; // Bad: Mapping 'Header' to 'Top' is not allowed
 ```
 
-(Don't) Use non-semantic or unclear subcomponent names:
+Use non-semantic or unclear subcomponent names
 ```
 Card/
   └── common/
@@ -583,7 +583,7 @@ Card/
       ├── Element/        # Bad: Too vague, not semantic - what element?
 ```
 
-(Don't) Nest subcomponents more than one level deep:
+Nest subcomponents more than one level deep
 ```typescript
 <Card>
   <Card.Header>
@@ -592,7 +592,7 @@ Card/
 </Card>
 ```
 
-(Don't) Export private subcomponents that are not intended for public use.
+Export private subcomponents that are not intended for public use.
 ```typescript
 // Bad: Exporting internal-only subcomponents
 export { InternalHelper };
@@ -606,7 +606,7 @@ Component TSDoc documentation must use the description from the design system on
 
 ### Do
 
-(Do) Use the description from the DSL ontology verbatim.
+Use the description from the DSL ontology verbatim.
 ```typescript
 /**
  * The label component is a compact, non-interactive visual element used to
@@ -625,7 +625,7 @@ const Label = ({ children, criticality, className, ...props }: LabelProps) => (
 
 ### Don't
 
-(Don't) Write custom descriptions that deviate from the DSL.
+Write custom descriptions that deviate from the DSL.
 ```typescript
 // Bad: Custom title and paraphrased description
 /**
@@ -635,21 +635,19 @@ const Label = ({ children, criticality, className, ...props }: LabelProps) => (
  */
 ```
 
-(Don't) Include @example blocks - stories fulfill this role.
+Include @example blocks - stories fulfill this role.
 ```typescript
 // Bad: Examples belong in stories, not TSDoc
 /**
  * The label component is a compact...
  *
  * @example
- * ```tsx
  * <Label>Default</Label>
  * <Label criticality="warning">Warning</Label>
- * ```
  */
 ```
 
-(Don't) Omit the @implements tag that links to the DSL.
+Omit the @implements tag that links to the DSL.
 ```typescript
 // Bad: Missing @implements tag
 /**
@@ -672,7 +670,7 @@ Each hook must define a [HookName]Props and [HookName]Result type in `hooks/type
 
 ### Do
 
-(Do) Create a custom hook that focuses on a single concern within the domain.
+Create a custom hook that focuses on a single concern within the domain.
 ```typescript
 // [MyComponent]/hooks/useWindowFitment.ts
 const useWindowFitment = ({
@@ -680,7 +678,8 @@ const useWindowFitment = ({
   autoFit = false,
 }: UseWindowFitmentProps): UseWindowFitmentResult => {
 ```
-(Do) Create hook types in `hooks/types.ts`.
+
+Create hook types in `hooks/types.ts`.
 ```typescript
 // [MyComponent]/hooks/types.ts
 export interface UseWindowFitmentProps {
@@ -718,7 +717,7 @@ export interface UseWindowFitmentResult {
 
 ### Don't
 
-(Don't) Create a custom hook for simple, non-reusable state.
+Create a custom hook for simple, non-reusable state.
 ```tsx
 // Bad: Unnecessary abstraction for a simple counter
 const useCounter = () => {
@@ -727,7 +726,7 @@ const useCounter = () => {
 };
 ```
 
-(Don't) Mix multiple concerns in a single hook
+Mix multiple concerns in a single hook
 ```typescript
 // Bad: Multiple concerns in one hook
 const useUserData = () => {
@@ -747,7 +746,7 @@ The hook name must start with 'use' and clearly describe its purpose.
 
 ### Do
 
-(Do) Name custom hooks so the hook name starts with 'use' and is descriptive:
+Name custom hooks so the hook name starts with 'use' and is descriptive
 ```typescript
 useWindowSize()
 useAuthentication()
@@ -756,7 +755,7 @@ useFormValidation()
 
 ### Don't
 
-(Don't) Name hooks without the 'use' prefix at the start of the hook name:
+Name hooks without the 'use' prefix at the start of the hook name
 ```typescript
 windowSize()
 getAuth()