diff --git a/docs/design/grid-layout.md b/docs/design/grid-layout.md new file mode 100644 index 000000000..e69de29bb diff --git a/docs/design/ssr-gen.md b/docs/design/ssr-gen.md new file mode 100644 index 000000000..e69de29bb diff --git a/docs/documentation/API-Documentation.md b/docs/documentation/API-Documentation.md new file mode 100644 index 000000000..72169cf4c --- /dev/null +++ b/docs/documentation/API-Documentation.md @@ -0,0 +1,72 @@ + +## JavaScript API (Imperative) + +Most of the **@angular/flex-layout** functionality is provided via Directives used **declaratively** in template HTML. There are three (3) programmatic features, however, that are published for programmatic usages: + +* **[ObservableMedia](https://github.com/angular/flex-layout/wiki/ObservableMedia)**:
Injectable Observable used to subscribe to MediaQuery activation changes.
+`constructor(public media:ObservableMedia ) { ... }` + +* **[BREAKPOINTS](https://github.com/angular/flex-layout/wiki/BreakPoints)**:
Opaque token used to override or extend the default breakpoints with custom MediaQuery breakpoints.
`providers: [{provide: BREAKPOINTS, useValue: MY_CUSTOM_BREAKPOINTS }]` + +* **[BaseFxDirectiveAdapter](https://github.com/angular/flex-layout/wiki/BaseFxDirectiveAdapter)**:
Adapter class useful to extend existing Directives with MediaQuery activation features.
`export class ClassDirective extends NgClass { ... }` + +
+ +## HTML API (Declarative) + +The features of Flex-Layout are best used, however, declaratively in template HTML. This API has two (2) significant feature sets: + +* **[Static API](https://github.com/angular/flex-layout/wiki/Declarative-API-Overview)**: Summary of static API features.
+* **[Responsive API](https://github.com/angular/flex-layout/wiki/Responsive-API)**: Introducing Responsive API and BreakPoints details.
+ +As each directive (aka API) within **@angular/flex-layout** has its own constraints and options, the links below should be used to navigate to the specific the documentation pages for each directive. + +
+ +### Containers + +This API set applies flexbox CSS stylings for DOM **container elements** with 1 or more nested flex children: + +* [**fxLayout**](https://github.com/angular/flex-layout/wiki/fxLayout-API):
Defines the flow order of child items within a flexbox container.
`
`
  +* **[fxLayoutWrap](https://github.com/angular/flex-layout/wiki/fxLayoutWrap-API)** :
Defines if child items appear on a single line or on multiple lines within a flexbox container.
`
`
  +* **[fxLayoutGap](https://github.com/angular/flex-layout/wiki/fxLayoutGap-API)**:
Defines if child items within a flexbox container should have a gap.
`
`
  +* **[fxLayoutAlign](https://github.com/angular/flex-layout/wiki/fxLayoutAlign-API)**:
Defines how flexbox items are aligned according to both the main-axis and the cross-axis, within a flexbox container.
`
` + + +
+ +### Child Elements within Containers + +This API set applies flexbox CSS stylings for a DOM element nested within FlexBox DOM container: + +* **[fxFlex](https://github.com/angular/flex-layout/wiki/fxFlex-API)**:
This markup specifies the resizing of its host element within a flexbox container flow.
`
` + +* **[fxFlexOrder](https://github.com/angular/flex-layout/wiki/fxFlexOrder-API)**:
Defines the order of a flexbox item.
`
` + +* **[fxFlexOffset](https://github.com/angular/flex-layout/wiki/fxFlexOffset-API)**:
Offset a flexbox item in its parent container flow layout.
`
` + +* **[fxFlexAlign](https://github.com/angular/flex-layout/wiki/fxFlexAlign-API)**:
Works like fxLayoutAlign, but applies only to a single flexbox item, instead of all of them.
`
` + +* **[fxFlexFill](https://github.com/angular/flex-layout/wiki/fxFlexFill-API)**:
Maximizes width and height of element in a layout container
`
` + + +
+ +### Special Responsive Features + +While the following APIs also add or remove DOM element inline styles, they are NOT FlexBox CSS specific. + +Instead these are **Responsive** APIs used to adjust specific, non-flexbox styles when a specific mediaQuery has activated: + +* **[fxShow](https://github.com/angular/flex-layout/wiki/fxShow-API)**:
This markup specifies if its host element should be displayed (or not).
`
` + +* **[fxHide](https://github.com/angular/flex-layout/wiki/fxHide-API)**:
This markup specifies if its host element should NOT be displayed.
`
` + + +* **[ngClass](https://github.com/angular/flex-layout/wiki/ngClass-API)** : +
Enhances the **ngClass** directives with class changes based on mediaQuery activations.
`
`. + +* **[ngStyle](https://github.com/angular/flex-layout/wiki/ngStyle-API)**: +
Enhances the **ngStyle** directive with style updates based on mediaQuery activations.
`
` + + diff --git a/docs/documentation/Adaptive-Layouts.md b/docs/documentation/Adaptive-Layouts.md new file mode 100644 index 000000000..514904245 --- /dev/null +++ b/docs/documentation/Adaptive-Layouts.md @@ -0,0 +1,59 @@ +Several Angular Material 1 applications: **[Material-Adaptive](https://github.com/angular/material-adaptive/tree/master/shrine)** have been implemented using custom Flexbox CSS. These efforts illustrated the needs and features within a responsive, adaptive application. + +* [Pesto](https://material-adaptive.firebaseapp.com/pesto/app/dist.html#/home) +* [Shring](https://material-adaptive.firebaseapp.com/shrine/app/dist.html) + +![screen shot 2016-11-05 at 7 26 56 am](https://cloud.githubusercontent.com/assets/210413/20029970/44c16d64-a329-11e6-9a9a-bd00561ea936.png) + +Different from responsive layouts where components change sizes and positions, the concepts of Adaptive layouts +provide for UX where **different components** may be used for different breakpoints. + +Animations can also be extended to support MediaQuery activations: different animations will run for different viewport sizes. + +Developers can use the following directives to achieve some Adaptive UX goals: + +* `fxHide` +* `fxShow` +* `ngIf` + +For examples of `fx-hide` usages in Adaptive layouts, please review the demo **Show & Hide Directives**: + +* [Demo](https://tburleson-layouts-demos.firebaseapp.com/#/responsive) +* [Source](https://github.com/angular/flex-layout/blob/master/src/demo-app/app/docs-layout-responsive/responsiveShowHide.demo.ts#L15) + +---- + +#### Core Directives + Responsive Features + +Responsive features for core Angular directives: + +* `[ngStyle.]=""` +* `[ngClass.]=""` +* `*ngIf.=""` is not yet supported. + +Here is the current solution solution to enabled responsive/adaptive features with **`*ngIf`**: + +```js +import {ObservableMedia} from '@angular/flex-layout'; + +@Component({ + selector : 'my-mobile-component', + template : ` +
+ This content is only shown on Mobile devices +
+
+ Current state: {{ }} +
+ ` +}) +export class MyMobileComponent { + public state = ''; + constructor(public media:ObservableMedia ) { + media.asObservable() + .subscribe((change:MediaChange) => { + this.state = change ? `'${change.mqAlias}' = (${change.mediaQuery})` : "" + }); + } +} +``` diff --git a/docs/documentation/Angular-Flex-Layout-Coding-Standards.md b/docs/documentation/Angular-Flex-Layout-Coding-Standards.md new file mode 100644 index 000000000..853c2ef84 --- /dev/null +++ b/docs/documentation/Angular-Flex-Layout-Coding-Standards.md @@ -0,0 +1,69 @@ +The [Google JavaScript Style Guide](https://google.github.io/styleguide/jsguide.html) is the +basis for our coding style, with additional guidance here where that style guide is not aligned with +ES6 or TypeScript. + +## Coding practices + +### General + +#### Write useful comments +Comments that explain what some block of code does are nice; they can tell you something in less time than it would take to follow through the code itself. + +Comments that explain why some block of code exists at all, or does something the way it does, +are _invaluable_. The "why" is difficult, or sometimes impossible, to track down without seeking out +the original author. When collaborators are in the same room, this hurts productivity. +When collaborators are in different timezones, this can be devastating to productivity. + +For example, this is a not-very-useful comment: +```ts +// Set default tabindex. +if (!$attrs['tabindex']) { + $element.attr('tabindex', '-1'); +} +``` + +While this is much more useful: +```ts +// Unless the user specifies so, the calendar should not be a tab stop. +// This is necessary because ngAria might add a tabindex to anything with an ng-model +// (based on whether or not the user has turned that particular feature on/off). +if (!$attrs['tabindex']) { + $element.attr('tabindex', '-1'); +} +``` + +#### Prefer more focused, granular components vs. complex, configurable components. + +For example, rather than doing this: +```html +Basic button +FAB +pony +``` + +do this: +```html +Basic button +FAB +pony +``` + +#### Prefer small, focused modules +Keeping modules to a single responsibility makes the code easier to test, consume, and maintain. +ES6 modules offer a straightforward way to organize code into logical, granular units. +Ideally, individual files are 200 - 300 lines of code. + +#### Less is more +Once a feature is released, it never goes away. We should avoid adding features that don't offer +high user value for price we pay both in maintenance, complexity, and payload size. When in doubt, +leave it out. + +This applies especially so to providing two different APIs to accomplish the same thing. Always +prefer sticking to a _single_ API for accomplishing something. + +### TypeScript + +#### Provide function descriptions +For functions that are more complicated than a simple getter/setter, provide at least a brief +sentence explaining what the function does and/or _why_ it does something. + diff --git a/docs/documentation/Background.md b/docs/documentation/Background.md new file mode 100644 index 000000000..0b3613d6b --- /dev/null +++ b/docs/documentation/Background.md @@ -0,0 +1,30 @@ +### Background + +The primary idea behind the flexbox layout is to give HTML DOM elements the ability to alter their width/height (and order) to best fill the available space... to *reflow* and *layout* for different kinds of display devices and different screen sizes. + +More importantly, flexbox css is direction-agnostic as opposed to the regular layouts (block which is vertically-based and inline which is horizontally-based). While those work well for some pages, they lack flexibility to support large or complex applications: especially when it comes to orientation changing, resizing, stretching, shrinking, etc. Especially important are *flex* features that resize elements to intelligently fill available spaces. A flex container expands items to fill available free space, or shrinks them to prevent overflow. + +Now let's add these complexities the requirements that developers often want combine the CSS Flexbox API with CSS media queries in order to support responsive layouts. e.g. + + + + + + +
+ +Unfortunately, developers manually implementing Flexbox CSS must become experts at both the syntax and the workarounds to accommodate browser-specific differences in Flexbox runtime support. + +Several Angular Material 1 applications: **[Material-Adaptive](https://github.com/angular/material-adaptive/tree/master/shrine)** have been implemented using custom Flexbox CSS. These efforts illustrated the needs and features within a responsive, adaptive application. + +* [Pesto](https://material-adaptive.firebaseapp.com/pesto/app/dist.html#/home) +* [Shring](https://material-adaptive.firebaseapp.com/shrine/app/dist.html) + +![screen shot 2016-11-05 at 7 26 56 am](https://cloud.githubusercontent.com/assets/210413/20029970/44c16d64-a329-11e6-9a9a-bd00561ea936.png) + +These additional feature ideas - derived from real-world Application implementations - have now been implemented within the Angular Flex-Layout library. Here are some of this libraries more notable features: + +* Direct DOM element CSS style injections +* Distinct responsive engine (MediaQuery change notifications with adapters) +* Subscription process for adaptive notifications to trigger custom Layout processes + diff --git a/docs/documentation/BreakPoints.md b/docs/documentation/BreakPoints.md new file mode 100644 index 000000000..a6504ff2f --- /dev/null +++ b/docs/documentation/BreakPoints.md @@ -0,0 +1,115 @@ +The token **BREAKPOINTS** is an opaque token in **@angular/flex-layout** that is used to build a **Provider** for a raw list of breakpoints. + +```js +import {OpaqueToken} from '@angular/core'; + +export const BreakPointsProvider = { + provide: BREAKPOINTS, + useValue: DEFAULT_BREAKPOINTS +}; +``` + +```js +@NgModule({ + providers: [ + BreakPointsProvider, // Supports developer overrides of list of known breakpoints + // BreakPointRegistry, // Registry of known/used BreakPoint(s) + // MatchMedia, // Low-level service to publish observables w/ window.matchMedia() + // MediaMonitor, // MediaQuery monitor service observes all known breakpoints + // ObservableMediaProvider // easy subscription injectable `media$` matchMedia observable + ] +}) +export class MediaQueriesModule { +} +``` + +This provider is used to return a list to ALL known BreakPoint(s)... and, in turn, this list is used internally to register mediaQueries and announce mediaQuery activations. + + +### Custom BreakPoints + +Using the **BREAKPOINTS** OpaqueToken, developers can add custom breakpoints or easily override existing breakpoints. + +For example to add mediaQueries that activate when printing: + +##### - `custom-breakpoints.ts` - + +```js +import {DEFAULT_BREAKPOINTS} from '@angular/flex-layout'; + +const PRINT_BREAKPOINTS = [{ + alias: 'xs.print', + suffix: 'XsPrint', + mediaQuery: 'print and (max-width: 297px)', + overlapping: false +}]; + +export const CustomBreakPointsProvider = { + provide: BREAKPOINTS, + useValue: [...DEFAULT_BREAKPOINTS,...PRINT_BREAKPOINTS]; +}; +``` + +##### - `my-app-module.ts` - + +```js +import { CustomBreakPointsProvider } from 'custom-breakpoints.ts'; + +@NgModule({ + imports : [ + CommonModule, + FlexLayoutModule, + ] + providers: [ + CustomBreakPointsProvider, // Adds breakpoints for 'print' mediaQueries + ] +}) +export class MyAppModule { +} +``` + +With the above changes, when printing on mobile-sized viewports the **`xs.print`** mediaQuery will activate. + +### Custom Breakpoints and Directives + +It must be noted that simply registering custom breakpoints will not automatically mean that Flex-Layout API will support those as selectors. + +In the above example the custom Breakpoint has been registered, but HTML selectors for **`xs.print`** will not work automatically. Consider the scenario below where some content should be hidden while printing and other content has different layouts while printing: + +```html +
+ ... +
+ +