Merge pull request zoltantothcom#35 from zoltantothcom/dev

zoltantothcom · web-flow · commit e9352b35ebea · 2019-03-15T09:48:55.000-04:00
Expand patterns details
diff --git a/__tests__/components/__snapshots__/Pattern.test.js.snap b/__tests__/components/__snapshots__/Pattern.test.js.snap
@@ -59,9 +59,19 @@ exports[`REFERENCE - Pattern component renders the individual pattern (Singleton
     <span
       className="c2"
     >
-      Description:
+      Definition:
     </span>
-    This pattern restricts object creation for a class to only one instance.
+    Ensure a class has only one instance and provide a global point of access to it.
+  </p>
+  <p>
+    <span
+      className="c2"
+    >
+      Use when…
+    </span>
+    …
+    there must by only one instance of a class
+    .
   </p>
   <h3>
     ES5
diff --git a/__tests__/pages/__snapshots__/Patterns.test.js.snap b/__tests__/pages/__snapshots__/Patterns.test.js.snap
@@ -295,9 +295,19 @@ exports[`Patterns page renders the individual Pattern (Singleton) info 1`] = `
     <span
       className="c2"
     >
-      Description:
+      Definition:
     </span>
-    This pattern restricts object creation for a class to only one instance.
+    Ensure a class has only one instance and provide a global point of access to it.
+  </p>
+  <p>
+    <span
+      className="c2"
+    >
+      Use when…
+    </span>
+    …
+    there must by only one instance of a class
+    .
   </p>
   <h3>
     ES5
diff --git a/src/components/Pattern.jsx b/src/components/Pattern.jsx
@@ -73,9 +73,15 @@ class Pattern extends React.Component {
               <Type>{pattern.type} pattern</Type>
             </p>
             <p>
-              <SubHeader>Description:</SubHeader>
-              {`This pattern ${pattern.hint}.`}
+              <SubHeader>Definition:</SubHeader>
+              {pattern.definition}
             </p>
+            {pattern.when && (
+              <p>
+                <SubHeader>Use when&hellip;</SubHeader>
+                &hellip;{pattern.when}.
+              </p>
+            )}
 
             <h3>ES5</h3>
             <SyntaxHighlighter language="javascript" style={style}>
diff --git a/src/static/patterns/behavioral_chainOfResponsibility.js b/src/static/patterns/behavioral_chainOfResponsibility.js
@@ -2,7 +2,10 @@ const CHAIN_OF_RESPONSIBILITY = {
   id: 'chain_of_responsibility',
   name: 'Chain of Responsibility',
   type: 'behavioral',
-  hint: 'delegates commands to a chain of processing objects',
+  hint: 'A way of passing a request between a chain of objects',
+  definition: `Avoid coupling the sender of a request to its receiver by giving more than one object a chance to
+    handle the request. Chain the receiving objects and pass the request along the chain until an object handles it.`,
+  when: 'more than one object can handle a request and that information is known in runtime',
   codeES5: `function ShoppingCart() {
   this.products = [];
 
diff --git a/src/static/patterns/behavioral_command.js b/src/static/patterns/behavioral_command.js
@@ -2,7 +2,11 @@ const COMMAND = {
   id: 'command',
   name: 'Command',
   type: 'behavioral',
-  hint: 'creates objects which encapsulate actions and parameters',
+  hint: 'Encapsulate a command request as an object',
+  definition: `Encapsulate a request as an object, thereby letting you parameterize clients with different requests,
+    queue or log requests, and support undoable operations.`,
+  when:
+    'you have a queue of requests to handle or you want to log them. Also when you want to have an «undo» action',
   codeES5: `function Cockpit(instruction) {
   this.instruction = instruction;
 }
diff --git a/src/static/patterns/behavioral_interpreter.js b/src/static/patterns/behavioral_interpreter.js
@@ -2,7 +2,11 @@ const INTERPRETER = {
   id: 'interpteter',
   name: 'Interpreter',
   type: 'behavioral',
-  hint: 'implements a specialized language',
+  hint: 'A way to include language elements in a program',
+  definition: `Given a language, define a representation for its grammar along with an interpreter that
+    uses the representation to interpret sentences in the language.`,
+  when:
+    'you want to interpret given language and you can represent statements as an abstract syntax trees',
   codeES5: `function Sum(left, right) {
   this.left = left;
   this.right = right;
diff --git a/src/static/patterns/behavioral_iterator.js b/src/static/patterns/behavioral_iterator.js
@@ -2,8 +2,10 @@ const ITERATOR = {
   id: 'iterator',
   name: 'Iterator',
   type: 'behavioral',
-  hint:
-    'accesses the elements of an object sequentially without exposing its underlying representation',
+  hint: 'Sequentially access the elements of a collection',
+  definition: `Provide a way to access the elements of an aggregate object sequentially
+    without exposing its underlying representation.`,
+  when: "you want to access object's content without knowing how it is internally represented",
   codeES5: `function Pattern(el) {
   this.index = 0;
   this.elements = el;
diff --git a/src/static/patterns/behavioral_mediator.js b/src/static/patterns/behavioral_mediator.js
@@ -2,8 +2,11 @@ const MEDIATOR = {
   id: 'mediator',
   name: 'Mediator',
   type: 'behavioral',
-  hint:
-    'allows loose coupling between classes by being the only class that has detailed knowledge of their methods',
+  hint: 'Defines simplified communication between classes',
+  definition: `Define an object that encapsulates how a set of objects interact.
+    Mediator promotes loose coupling by keeping objects from referring to each other explicitly,
+    and it lets you vary their interaction independently.`,
+  when: 'a set of objects communicate in structured but complex ways',
   codeES5: `function TrafficTower() {
   this.airplanes = [];
 }
diff --git a/src/static/patterns/behavioral_memento.js b/src/static/patterns/behavioral_memento.js
@@ -2,7 +2,10 @@ const MEMENTO = {
   id: 'memento',
   name: 'Memento',
   type: 'behavioral',
-  hint: 'provides the ability to restore an object to its previous state',
+  hint: "Capture and restore an object's internal state",
+  definition: `Without violating encapsulation, capture and externalize an object's internal state
+    so that the object can be restored to this state later.`,
+  when: 'you need to take a snapshot of an object',
   codeES5: `function Pattern(value) {
   this.value = value;
 }
diff --git a/src/static/patterns/behavioral_observer.js b/src/static/patterns/behavioral_observer.js
@@ -2,7 +2,10 @@ const OBSERVER = {
   id: 'observer',
   name: 'Observer',
   type: 'behavioral',
-  hint: 'is a publish/subscribe pattern which allows a number of observer objects to see an event',
+  hint: 'A way of notifying change to a number of classes',
+  definition: `Define a one-to-many dependency between objects so that when one object changes state,
+    all its dependents are notified and updated automatically.`,
+  when: 'a change to one object requires changing others',
   codeES5: `function Product() {
   this.price = 0;
   this.actions = [];
diff --git a/src/static/patterns/behavioral_state.js b/src/static/patterns/behavioral_state.js
@@ -2,7 +2,10 @@ const STATE = {
   id: 'state',
   name: 'State',
   type: 'behavioral',
-  hint: 'allows an object to alter its behavior when its internal state changes',
+  hint: "Alter an object's behavior when its state changes",
+  definition: `Allow an object to alter its behavior when its internal state changes.
+    The object will appear to change its class.`,
+  when: `the object's behaviour depends on its state and its behaviour changes in run-time depends on that state`,
   codeES5: `function Order() {
   this.pattern = new WaitingForPayment();
 
diff --git a/src/static/patterns/behavioral_strategy.js b/src/static/patterns/behavioral_strategy.js
@@ -2,7 +2,11 @@ const STRATEGY = {
   id: 'strategy',
   name: 'Strategy',
   type: 'behavioral',
-  hint: 'allows one of a family of algorithms to be selected on-the-fly at runtime',
+  hint: 'Encapsulates an algorithm inside a class',
+  definition: `Define a family of algorithms, encapsulate each one, and make them interchangeable.
+    Strategy lets the algorithm vary independently from clients that use it.`,
+  when: `you have many classes that differ in their behaviour.
+    Strategies allow to configure a class with one of many behaviours`,
   codeES5: `function ShoppingCart(discount) {
   this.discount = discount;
   this.amount = 0;
diff --git a/src/static/patterns/behavioral_template.js b/src/static/patterns/behavioral_template.js
@@ -2,8 +2,10 @@ const TEMPLATE = {
   id: 'template',
   name: 'Template',
   type: 'behavioral',
-  hint:
-    'defines the skeleton of an algorithm as an abstract class, allowing its subclasses to provide concrete behavior',
+  hint: 'Defer the exact steps of an algorithm to a subclass',
+  definition: `Define the skeleton of an algorithm in an operation, deferring some steps to subclasses.
+    Template Method lets subclasses redefine certain steps of an algorithm without changing the algorithm's structure.`,
+  when: `you have to define steps of the algorithm once and let subclasses to implement its behaviour`,
   codeES5: `function Tax() {}
 
 Tax.prototype.calc = function(value) {
diff --git a/src/static/patterns/behavioral_visitor.js b/src/static/patterns/behavioral_visitor.js
@@ -2,8 +2,11 @@ const VISITOR = {
   id: 'visitor',
   name: 'Visitor',
   type: 'behavioral',
-  hint:
-    'separates an algorithm from an object structure by moving the hierarchy of methods into one object',
+  hint: 'Defines a new operation to a class without change',
+  definition: `Represent an operation to be performed on the elements of an object structure.
+    Visitor lets you define a new operation without changing the classes of the elements on which it operates.`,
+  when: `an object structure includes many classes and you want to perform an operations
+    on the elements of that structure that depend on their classes`,
   codeES5: `function bonusPattern(employee) {
   if (employee instanceof Manager) employee.bonus = employee.salary * 2;
   if (employee instanceof Developer) employee.bonus = employee.salary;
diff --git a/src/static/patterns/creational_abstractFactory.js b/src/static/patterns/creational_abstractFactory.js
@@ -2,7 +2,10 @@ const ABSTRACT_FACTORY = {
   id: 'abstract_factory',
   name: 'Abstract Factory',
   type: 'creational',
-  hint: 'groups object factories that have a common theme',
+  hint: 'Creates an instance of several families of classes',
+  definition: `Provide an interface for creating families of related or dependent objects
+    without specifying their concrete classes.`,
+  when: 'system should be independent of how what it is producing is structured or represented',
   codeES5: `function droidProducer(kind) {
   if (kind === 'battle') return battleDroidPattern;
   return pilotDroidPattern;
diff --git a/src/static/patterns/creational_builder.js b/src/static/patterns/creational_builder.js
@@ -2,7 +2,10 @@ const BUILDER = {
   id: 'builder',
   name: 'Builder',
   type: 'creational',
-  hint: 'constructs complex objects by separating construction and representation',
+  hint: 'Separates object construction from its representation',
+  definition: `Separate the construction of a complex object from its representation
+    so that the same construction process can create different representations.`,
+  when: 'algorithm of creation is independent of the parts of the object',
   codeES5: `function Request() {
   this.url = '';
   this.method = '';
diff --git a/src/static/patterns/creational_factory.js b/src/static/patterns/creational_factory.js
@@ -2,7 +2,10 @@ const FACTORY = {
   id: 'factory',
   name: 'Factory',
   type: 'creational',
-  hint: 'creates objects without specifying the exact class to create',
+  hint: 'Creates an instance of several derived classes',
+  definition: `Define an interface for creating an object, but let subclasses decide
+    which class to instantiate. Factory Method lets a class defer instantiation to subclasses.`,
+  when: `a class wants its subclasses to decide which object to create`,
   codeES5: `function teslaPattern(type) {
   if (type === 'ModelX') return new Tesla(type, 108000, 300);
   if (type === 'ModelS') return new Tesla(type, 111000, 320);
diff --git a/src/static/patterns/creational_prototype.js b/src/static/patterns/creational_prototype.js
@@ -2,7 +2,10 @@ const PROTOTYPE = {
   id: 'prototype',
   name: 'Prototype',
   type: 'creational',
-  hint: 'creates objects by cloning an existing object',
+  hint: 'A fully initialized instance to be copied or cloned',
+  definition: `Specify the kind of objects to create using a prototypical instance,
+    and create new objects by copying this prototype.`,
+  when: 'classes to instantiate are available only in runtime',
   codeES5: `function Sheep(name, weight) {
   this.name = name;
   this.weight = weight;
diff --git a/src/static/patterns/creational_singleton.js b/src/static/patterns/creational_singleton.js
@@ -2,7 +2,9 @@ const SINGLETON = {
   id: 'singleton',
   name: 'Singleton',
   type: 'creational',
-  hint: 'restricts object creation for a class to only one instance',
+  hint: 'A class of which only a single instance can exist',
+  definition: 'Ensure a class has only one instance and provide a global point of access to it.',
+  when: 'there must by only one instance of a class',
   codeES5: `function Person() {
   if (typeof Person.instance === 'object') return Person.instance;
 
diff --git a/src/static/patterns/structural_adapter.js b/src/static/patterns/structural_adapter.js
@@ -2,8 +2,10 @@ const ADAPTER = {
   id: 'adapter',
   name: 'Adapter',
   type: 'structural',
-  hint: `allows classes with incompatible interfaces to work together by wrapping
-  its own interface around that of an already existing class`,
+  hint: `Match interfaces of different classes`,
+  definition: `Convert the interface of a class into another interface clients expect.
+    Adapter lets classes work together that couldn't otherwise because of incompatible interfaces.`,
+  when: `you want to use existing class but its interface does not match the one you need`,
   codeES5: `function Soldier(lvl) {
   this.lvl = lvl;
 }
diff --git a/src/static/patterns/structural_bridge.js b/src/static/patterns/structural_bridge.js
@@ -2,7 +2,10 @@ const BRIDGE = {
   id: 'bridge',
   name: 'Bridge',
   type: 'structural',
-  hint: 'decouples an abstraction from its implementation so that the two can vary independently',
+  hint: 'Separates an object’s interface from its implementation',
+  definition: `Decouple an abstraction from its implementation so that the two can vary independently.`,
+  when: `you want to avoid binding between abstraction and its implementation if, for example,
+    each of them must be selected in runtime`,
   codeES5: `function EpsonPrinter(ink) {
   this.ink = ink();
 }
diff --git a/src/static/patterns/structural_composite.js b/src/static/patterns/structural_composite.js
@@ -2,7 +2,10 @@ const COMPOSITE = {
   id: 'composite',
   name: 'Composite',
   type: 'structural',
-  hint: 'composes zero-or-more similar objects so that they can be manipulated as one object',
+  hint: 'A tree structure of simple and composite objects',
+  definition: `Compose objects into tree structures to represent part-whole hierarchies.
+    Composite lets clients treat individual objects and compositions of objects uniformly.`,
+  when: `you want to represent hierarchies of objects`,
   codeES5: `function EquipmentPattern(name) {
   this.equipments = [];
   this.name = name;
diff --git a/src/static/patterns/structural_decorator.js b/src/static/patterns/structural_decorator.js
@@ -2,7 +2,10 @@ const DECORATOR = {
   id: 'decorator',
   name: 'Decorator',
   type: 'structural',
-  hint: 'dynamically adds/overrides behaviour in an existing method of an object',
+  hint: 'Add responsibilities to objects dynamically',
+  definition: `Attach additional responsibilities to an object dynamically.
+    Decorators provide a flexible alternative to subclassing for extending functionality.`,
+  when: `you want to add extensions to an object in runtime without affecting other objects`,
   codeES5: `function Pasta() {
   this.price = 0;
 }
diff --git a/src/static/patterns/structural_facade.js b/src/static/patterns/structural_facade.js
@@ -2,7 +2,10 @@ const FACADE = {
   id: 'facade',
   name: 'Facade',
   type: 'structural',
-  hint: 'provides a simplified interface to a large body of code',
+  hint: 'A single class that represents an entire subsystem',
+  definition: `Provide a unified interface to a set of interfaces in a subsystem.
+    Facade defines a higher-level interface that makes the subsystem easier to use.`,
+  when: `you want to provide a simple interface to a complex subsystem`,
   codeES5: `var shopPattern = {
   calc: function(price) {
     price = discount(price);
diff --git a/src/static/patterns/structural_flyweight.js b/src/static/patterns/structural_flyweight.js
@@ -2,7 +2,9 @@ const FLYWEIGHT = {
   id: 'flyweight',
   name: 'Flyweight',
   type: 'structural',
-  hint: 'reduces the cost of creating and manipulating a large number of similar objects',
+  hint: 'A fine-grained instance used for efficient sharing',
+  definition: `Use sharing to support large numbers of fine-grained objects efficiently.`,
+  when: `an application uses a lot of small objects and their storing is expensive or their identity is not important`,
   codeES5: `function Color(name) {
   this.name = name;
 }
diff --git a/src/static/patterns/structural_proxy.js b/src/static/patterns/structural_proxy.js
@@ -2,8 +2,9 @@ const PROXY = {
   id: 'proxy',
   name: 'Proxy',
   type: 'structural',
-  hint:
-    'provides a placeholder for another object to control access, reduce cost, and reduce complexity',
+  hint: 'An object representing another object',
+  definition: `Provide a surrogate or placeholder for another object to control access to it.`,
+  when: ``,
   codeES5: `function Car() {
   this.drive = function() {
     return 'driving';
