shadcn_flutter Development Guide

Expert guidance for maintaining CHANGELOG.md, writing comprehensive Dart/Flutter API documentation, and testing components in the shadcn_flutter ecosystem.

CHANGELOG Maintenance

When to Update

Update `CHANGELOG.md` in the same PR whenever making user-visible changes:

Structure

Follow Keep a Changelog format with version sections and categories:

```markdown

Changelog

[Unreleased]

Added

Changed

Fixed

Breaking Changes

[1.2.0]

```

Entry Format

Each bullet includes:

Examples:

Breaking Changes

Must include:

1. Bullet under `### Breaking Changes` with explanation

2. Short migration guide (2-6 steps) with before/after examples

3. Version/config requirements

Example:

```markdown

Migration guide:

1. Replace `WidgetX` with `WidgetY`.

​```dart

// before

WidgetX(a: 1)

// after

WidgetY(a: 1, options: DefaultOptions())

​```

2. Rename styles from `x-` to `y-` in CSS.

Notes: `WidgetY` changes default serialization; bump to v2.0.0.

```

Retroactive Updates

When changes merged without CHANGELOG updates:

1. Identify PR/commit(s)

2. Read commit message for description

3. If message is vague:

- Calculate diff size (inserted + deleted lines)

- If < 1000 lines: parse diff and create detailed bullets

- If >= 1000 lines: write brief summary with "manual review required" note

4. Detect breaking changes and add migration guides

5. Combine, deduplicate, use imperative tone

Dart/Flutter Documentation

Critical Formatting Rules

**Generic Types in Documentation:**

This prevents `unintended_html_in_doc_comment` analyzer warnings.

Standard Documentation Structure

1. Short summary line

2. Overview paragraph(s)

3. Parameters (bulleted with types/defaults)

4. Returns

5. Errors/Assertions

6. Example(s)

7. Notes/Edge cases

8. See also

Parameter Documentation Pattern

```dart

/// Parameters:

/// - [onChanged] (`ValueChanged<T>?`, optional): Called when the value changes.

/// - [controller] (`ComponentController<T>?`, optional): External state source.

/// - [items] (`List<Widget>`, required): Widgets to display.

```

Class Documentation Template

```dart

/// A concise one-sentence summary of what this component does.

///

/// Longer overview explaining when and why to use it. Mention key behaviors,

/// lifecycle, state interactions, and customization points.

///

/// Parameters:

/// - [param1] (`Type`, required): What it does.

/// - [param2] (`Type?`, optional): What it does.

/// - [onChanged] (`ValueChanged<T>?`, optional): When it fires and how.

///

/// Example:

/// ```dart

/// MyComponent(

/// value: 42,

/// onChanged: (v) => print(v),

/// )

/// ```

class MyComponent<T> extends StatelessWidget {

// ...

}

```

Constructor Documentation

```dart

/// Creates a [MyComponent].

///

/// Describe constructor-specific behavior or constraints.

///

/// Parameters:

/// - [value] (`T`, required): Target value.

/// - [duration] (`Duration`, required): Animation duration.

/// - [curve] (`Curve`, default: `Curves.linear`): Timing curve.

/// - [onEnd] (`VoidCallback?`, optional): Called when complete.

///

/// Example:

/// ```dart

/// MyComponent<int>(

/// value: 10,

/// duration: const Duration(milliseconds: 300),

/// )

/// ```

const MyComponent({ /* ... */ });

```

Method Documentation

```dart

/// One-line description of what this does.

///

/// Longer explanation with context, inputs/outputs, and side-effects.

///

/// Parameters:

/// - [source] (`Iterable<T>`, required): Items to process.

/// - [predicate] (`bool Function(T)`, optional): Filter condition.

///

/// Returns: `List<T>` — the filtered items.

///

/// Example:

/// ```dart

/// final result = filter<int>([1,2,3], (x) => x.isOdd);

/// ```

List<T> filter<T>(Iterable<T> source, [bool Function(T)? predicate]) { /* ... */ }

```

Component Testing

Test Coverage Checklist

All public components must have comprehensive widget tests covering:

**Rendering & Layout:**

**Interactivity:**

**Theming & Variants:**

**Accessibility:**

**Internationalization:**

**Responsiveness:**

**Error Handling:**

Minimal Test Template

```dart

import 'package:flutter_test/flutter_test.dart';

import 'package:flutter/material.dart';

void main() {

testWidgets('renders and is visible', (tester) async {

await tester.pumpWidget(

MaterialApp(

theme: ThemeData.light(),

home: Scaffold(body: YourComponent()),

),

);

expect(find.byType(YourComponent), findsOneWidget);

});

testWidgets('responds to tap', (tester) async {

var tapped = false;

await tester.pumpWidget(

MaterialApp(

home: YourComponent(onTap: () => tapped = true),

),

);

await tester.tap(find.byType(YourComponent));

await tester.pumpAndSettle();

expect(tapped, isTrue);

});

}

```

Test Organization

Quality Checks

Before committing: